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.hc.core5.http.nio;
29
30 import java.io.IOException;
31 import java.nio.ByteBuffer;
32 import java.nio.channels.ReadableByteChannel;
33 import java.nio.channels.WritableByteChannel;
34
35 import org.apache.hc.core5.util.CharArrayBuffer;
36
37 /**
38 * Session input buffer for HTTP/1.1 non-blocking connections.
39 * <p>
40 * This interface facilitates intermediate buffering of input data streamed from
41 * a source channel and provides methods for reading lines of text.
42 * </p>
43 *
44 * @since 4.0
45 */
46 public interface SessionInputBuffer {
47
48 /**
49 * Determines if the buffer contains data.
50 *
51 * @return {@code true} if there is data in the buffer,
52 * {@code false} otherwise.
53 */
54 boolean hasData();
55
56 /**
57 * Returns the length of this buffer.
58 *
59 * @return buffer length.
60 */
61 int length();
62
63 /**
64 * Makes an attempt to fill the buffer with data from the given
65 * {@link ReadableByteChannel}.
66 *
67 * @param src the source channel
68 * @return The number of bytes read, possibly zero, or {@code -1} if the
69 * channel has reached end-of-stream.
70 * @throws IOException in case of an I/O error.
71 */
72 int fill(ReadableByteChannel src) throws IOException;
73
74 /**
75 * Reads one byte from the buffer. If the buffer is empty this method can
76 * throw a runtime exception. The exact type of runtime exception thrown
77 * by this method depends on implementation.
78 *
79 * @return one byte
80 */
81 int read();
82
83 /**
84 * Reads a sequence of bytes from this buffer into the destination buffer,
85 * up to the given maximum limit. The exact number of bytes transferred
86 * depends on availability of data in this buffer and capacity of the
87 * destination buffer, but cannot be more than {@code maxLen} value.
88 *
89 * @param dst the destination buffer.
90 * @param maxLen the maximum number of bytes to be read.
91 * @return The number of bytes read, possibly zero.
92 */
93 int read(ByteBuffer dst, int maxLen);
94
95 /**
96 * Reads a sequence of bytes from this buffer into the destination buffer.
97 * The exact number of bytes transferred depends on availability of data
98 * in this buffer and capacity of the destination buffer.
99 *
100 * @param dst the destination buffer.
101 * @return The number of bytes read, possibly zero.
102 */
103 int read(ByteBuffer dst);
104
105 /**
106 * Reads a sequence of bytes from this buffer into the destination channel,
107 * up to the given maximum limit. The exact number of bytes transferred
108 * depends on availability of data in this buffer, but cannot be more than
109 * {@code maxLen} value.
110 *
111 * @param dst the destination channel.
112 * @param maxLen the maximum number of bytes to be read.
113 * @return The number of bytes read, possibly zero.
114 * @throws IOException in case of an I/O error.
115 */
116 int read(WritableByteChannel dst, int maxLen) throws IOException;
117
118 /**
119 * Reads a sequence of bytes from this buffer into the destination channel.
120 * The exact number of bytes transferred depends on availability of data in
121 * this buffer.
122 *
123 * @param dst the destination channel.
124 * @return The number of bytes read, possibly zero.
125 * @throws IOException in case of an I/O error.
126 */
127 int read(WritableByteChannel dst) throws IOException;
128
129 /**
130 * Attempts to transfer a complete line of characters up to a line delimiter
131 * from this buffer to the destination buffer. If a complete line is
132 * available in the buffer, the sequence of chars is transferred to the
133 * destination buffer the method returns {@code true}. The line
134 * delimiter itself is discarded. If a complete line is not available in
135 * the buffer, this method returns {@code false} without transferring
136 * anything to the destination buffer. If {@code endOfStream} parameter
137 * is set to {@code true} this method assumes the end of stream has
138 * been reached and the content currently stored in the buffer should be
139 * treated as a complete line.
140 * <p>
141 * The choice of a char encoding and line delimiter sequence is up to the
142 * specific implementations of this interface.
143 *
144 * @param dst the destination buffer.
145 * @param endOfStream end of stream flag
146 * @return {@code true} if a sequence of chars representing a complete
147 * line has been transferred to the destination buffer, {@code false}
148 * otherwise.
149 *
150 * @throws java.nio.charset.CharacterCodingException in case a character encoding or decoding
151 * error occurs.
152 * @throws org.apache.hc.core5.http.MessageConstraintException in case a message constraint violation.
153 */
154 boolean readLine(CharArrayBuffer dst, boolean endOfStream) throws IOException;
155
156 }