1 /* 2 * ==================================================================== 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * ==================================================================== 20 * 21 * This software consists of voluntary contributions made by many 22 * individuals on behalf of the Apache Software Foundation. For more 23 * information on the Apache Software Foundation, please see 24 * <http://www.apache.org/>. 25 * 26 */ 27 28 package org.apache.http.nio.reactor; 29 30 import java.io.IOException; 31 import java.nio.ByteBuffer; 32 import java.nio.channels.ReadableByteChannel; 33 import java.nio.channels.WritableByteChannel; 34 import java.nio.charset.CharacterCodingException; 35 36 import org.apache.http.util.CharArrayBuffer; 37 38 /** 39 * Session input buffer for non-blocking connections. This interface facilitates 40 * intermediate buffering of input data streamed from a source channel and 41 * reading buffered data to a destination, usually {@link ByteBuffer} or 42 * {@link WritableByteChannel}. This interface also provides methods for reading 43 * lines of text. 44 * 45 * @since 4.0 46 */ 47 public interface SessionInputBuffer { 48 49 /** 50 * Determines if the buffer contains data. 51 * 52 * @return {@code true} if there is data in the buffer, 53 * {@code false} otherwise. 54 */ 55 boolean hasData(); 56 57 /** 58 * Returns the length of this buffer. 59 * 60 * @return buffer length. 61 */ 62 int length(); 63 64 /** 65 * Makes an attempt to fill the buffer with data from the given 66 * {@link ReadableByteChannel}. 67 * 68 * @param src the source channel 69 * @return The number of bytes read, possibly zero, or {@code -1} if the 70 * channel has reached end-of-stream. 71 * @throws IOException in case of an I/O error. 72 */ 73 int fill(ReadableByteChannel src) throws IOException; 74 75 /** 76 * Reads one byte from the buffer. If the buffer is empty this method can 77 * throw a runtime exception. The exact type of runtime exception thrown 78 * by this method depends on implementation. 79 * 80 * @return one byte 81 */ 82 int read(); 83 84 /** 85 * Reads a sequence of bytes from this buffer into the destination buffer, 86 * up to the given maximum limit. The exact number of bytes transferred 87 * depends on availability of data in this buffer and capacity of the 88 * destination buffer, but cannot be more than {@code maxLen} value. 89 * 90 * @param dst the destination buffer. 91 * @param maxLen the maximum number of bytes to be read. 92 * @return The number of bytes read, possibly zero. 93 */ 94 int read(ByteBuffer dst, int maxLen); 95 96 /** 97 * Reads a sequence of bytes from this buffer into the destination buffer. 98 * The exact number of bytes transferred depends on availability of data 99 * in this buffer and capacity of the destination buffer. 100 * 101 * @param dst the destination buffer. 102 * @return The number of bytes read, possibly zero. 103 */ 104 int read(ByteBuffer dst); 105 106 /** 107 * Reads a sequence of bytes from this buffer into the destination channel, 108 * up to the given maximum limit. The exact number of bytes transferred 109 * depends on availability of data in this buffer, but cannot be more than 110 * {@code maxLen} value. 111 * 112 * @param dst the destination channel. 113 * @param maxLen the maximum number of bytes to be read. 114 * @return The number of bytes read, possibly zero. 115 * @throws IOException in case of an I/O error. 116 */ 117 int read(WritableByteChannel dst, int maxLen) throws IOException; 118 119 /** 120 * Reads a sequence of bytes from this buffer into the destination channel. 121 * The exact number of bytes transferred depends on availability of data in 122 * this buffer. 123 * 124 * @param dst the destination channel. 125 * @return The number of bytes read, possibly zero. 126 * @throws IOException in case of an I/O error. 127 */ 128 int read(WritableByteChannel dst) throws IOException; 129 130 /** 131 * Attempts to transfer a complete line of characters up to a line delimiter 132 * from this buffer to the destination buffer. If a complete line is 133 * available in the buffer, the sequence of chars is transferred to the 134 * destination buffer the method returns {@code true}. The line 135 * delimiter itself is discarded. If a complete line is not available in 136 * the buffer, this method returns {@code false} without transferring 137 * anything to the destination buffer. If {@code endOfStream} parameter 138 * is set to {@code true} this method assumes the end of stream has 139 * been reached and the content currently stored in the buffer should be 140 * treated as a complete line. 141 * <p> 142 * The choice of a char encoding and line delimiter sequence is up to the 143 * specific implementations of this interface. 144 * 145 * @param dst the destination buffer. 146 * @param endOfStream end of stream flag 147 * @return {@code true} if a sequence of chars representing a complete 148 * line has been transferred to the destination buffer, {@code false} 149 * otherwise. 150 * 151 * @throws CharacterCodingException in case a character encoding or decoding 152 * error occurs. 153 */ 154 boolean readLine(CharArrayBuffer dst, boolean endOfStream) 155 throws CharacterCodingException; 156 157 /** 158 * Attempts to transfer a complete line of characters up to a line delimiter 159 * from this buffer to a newly created string. If a complete line is 160 * available in the buffer, the sequence of chars is transferred to a newly 161 * created string. The line delimiter itself is discarded. If a complete 162 * line is not available in the buffer, this method returns 163 * {@code null}. If {@code endOfStream} parameter 164 * is set to {@code true} this method assumes the end of stream has 165 * been reached and the content currently stored in the buffer should be 166 * treated as a complete line. 167 * <p> 168 * The choice of a char encoding and line delimiter sequence is up to the 169 * specific implementations of this interface. 170 * 171 * @param endOfStream end of stream flag 172 * @return a string representing a complete line, if available. 173 * {@code null} otherwise. 174 * 175 * @throws CharacterCodingException in case a character encoding or decoding 176 * error occurs. 177 */ 178 String readLine(boolean endOfStream) 179 throws CharacterCodingException; 180 181 }