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