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 }