1 /*
2 * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.0.1/httpcore/src/main/java/org/apache/http/io/SessionInputBuffer.java $
3 * $Revision: 744527 $
4 * $Date: 2009-02-14 18:06:25 +0100 (Sat, 14 Feb 2009) $
5 *
6 * ====================================================================
7 * Licensed to the Apache Software Foundation (ASF) under one
8 * or more contributor license agreements. See the NOTICE file
9 * distributed with this work for additional information
10 * regarding copyright ownership. The ASF licenses this file
11 * to you under the Apache License, Version 2.0 (the
12 * "License"); you may not use this file except in compliance
13 * with the License. You may obtain a copy of the License at
14 *
15 * http://www.apache.org/licenses/LICENSE-2.0
16 *
17 * Unless required by applicable law or agreed to in writing,
18 * software distributed under the License is distributed on an
19 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20 * KIND, either express or implied. See the License for the
21 * specific language governing permissions and limitations
22 * under the License.
23 * ====================================================================
24 *
25 * This software consists of voluntary contributions made by many
26 * individuals on behalf of the Apache Software Foundation. For more
27 * information on the Apache Software Foundation, please see
28 * <http://www.apache.org/>.
29 *
30 */
31
32 package org.apache.http.io;
33
34 import java.io.IOException;
35
36 import org.apache.http.util.CharArrayBuffer;
37
38 /**
39 * Session input buffer for blocking connections. This interface is similar to
40 * InputStream class, but it also provides methods for reading lines of text.
41 * <p>
42 * Implementing classes are also expected to manage intermediate data buffering
43 * for optimal input performance.
44 *
45 *
46 * @version $Revision: 744527 $
47 *
48 * @since 4.0
49 */
50 public interface SessionInputBuffer {
51
52 /**
53 * Reads up to <code>len</code> bytes of data from the session buffer into
54 * an array of bytes. An attempt is made to read as many as
55 * <code>len</code> bytes, but a smaller number may be read, possibly
56 * zero. The number of bytes actually read is returned as an integer.
57 *
58 * <p> This method blocks until input data is available, end of file is
59 * detected, or an exception is thrown.
60 *
61 * <p> If <code>off</code> is negative, or <code>len</code> is negative, or
62 * <code>off+len</code> is greater than the length of the array
63 * <code>b</code>, then an <code>IndexOutOfBoundsException</code> is
64 * thrown.
65 *
66 * @param b the buffer into which the data is read.
67 * @param off the start offset in array <code>b</code>
68 * at which the data is written.
69 * @param len the maximum number of bytes to read.
70 * @return the total number of bytes read into the buffer, or
71 * <code>-1</code> if there is no more data because the end of
72 * the stream has been reached.
73 * @exception IOException if an I/O error occurs.
74 */
75 int read(byte[] b, int off, int len) throws IOException;
76
77 /**
78 * Reads some number of bytes from the session buffer and stores them into
79 * the buffer array <code>b</code>. The number of bytes actually read is
80 * returned as an integer. This method blocks until input data is
81 * available, end of file is detected, or an exception is thrown.
82 *
83 * @param b the buffer into which the data is read.
84 * @return the total number of bytes read into the buffer, or
85 * <code>-1</code> is there is no more data because the end of
86 * the stream has been reached.
87 * @exception IOException if an I/O error occurs.
88 */
89 int read(byte[] b) throws IOException;
90
91 /**
92 * Reads the next byte of data from this session buffer. The value byte is
93 * returned as an <code>int</code> in the range <code>0</code> to
94 * <code>255</code>. If no byte is available because the end of the stream
95 * has been reached, the value <code>-1</code> is returned. This method
96 * blocks until input data is available, the end of the stream is detected,
97 * or an exception is thrown.
98 *
99 * @return the next byte of data, or <code>-1</code> if the end of the
100 * stream is reached.
101 * @exception IOException if an I/O error occurs.
102 */
103 int read() throws IOException;
104
105 /**
106 * Reads a complete line of characters up to a line delimiter from this
107 * session buffer into the given line buffer. The number of chars actually
108 * read is returned as an integer. The line delimiter itself is discarded.
109 * If no char is available because the end of the stream has been reached,
110 * the value <code>-1</code> is returned. This method blocks until input
111 * data is available, end of file is detected, or an exception is thrown.
112 * <p>
113 * The choice of a char encoding and line delimiter sequence is up to the
114 * specific implementations of this interface.
115 *
116 * @param buffer the line buffer.
117 * @return one line of characters
118 * @exception IOException if an I/O error occurs.
119 */
120 int readLine(CharArrayBuffer buffer) throws IOException;
121
122 /**
123 * Reads a complete line of characters up to a line delimiter from this
124 * session buffer. The line delimiter itself is discarded. If no char is
125 * available because the end of the stream has been reached,
126 * <code>null</code> is returned. This method blocks until input data is
127 * available, end of file is detected, or an exception is thrown.
128 * <p>
129 * The choice of a char encoding and line delimiter sequence is up to the
130 * specific implementations of this interface.
131 *
132 * @return HTTP line as a string
133 * @exception IOException if an I/O error occurs.
134 */
135 String readLine() throws IOException;
136
137 /** Blocks until some data becomes available in the session buffer or the
138 * given timeout period in milliseconds elapses. If the timeout value is
139 * <code>0</code> this method blocks indefinitely.
140 *
141 * @param timeout in milliseconds.
142 * @return <code>true</code> if some data is available in the session
143 * buffer or <code>false</code> otherwise.
144 * @exception IOException if an I/O error occurs.
145 */
146 boolean isDataAvailable(int timeout) throws IOException;
147
148 /**
149 * Returns {@link HttpTransportMetrics} for this session buffer.
150 *
151 * @return transport metrics.
152 */
153 HttpTransportMetrics getMetrics();
154
155 }