001/*
002 * ====================================================================
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 * ====================================================================
020 *
021 * This software consists of voluntary contributions made by many
022 * individuals on behalf of the Apache Software Foundation.  For more
023 * information on the Apache Software Foundation, please see
024 * <http://www.apache.org/>.
025 *
026 */
027
028package org.apache.http.io;
029
030import java.io.IOException;
031
032import org.apache.http.util.CharArrayBuffer;
033
034/**
035 * Session input buffer for blocking connections. This interface is similar to
036 * InputStream class, but it also provides methods for reading lines of text.
037 * <p>
038 * Implementing classes are also expected to manage intermediate data buffering
039 * for optimal input performance.
040 *
041 * @since 4.0
042 */
043public interface SessionInputBuffer {
044
045    /**
046     * Reads up to {@code len} bytes of data from the session buffer into
047     * an array of bytes.  An attempt is made to read as many as
048     * {@code len} bytes, but a smaller number may be read, possibly
049     * zero. The number of bytes actually read is returned as an integer.
050     *
051     * <p> This method blocks until input data is available, end of file is
052     * detected, or an exception is thrown.
053     *
054     * <p> If {@code off} is negative, or {@code len} is negative, or
055     * {@code off+len} is greater than the length of the array
056     * {@code b}, then an {@code IndexOutOfBoundsException} is
057     * thrown.
058     *
059     * @param      b     the buffer into which the data is read.
060     * @param      off   the start offset in array {@code b}
061     *                   at which the data is written.
062     * @param      len   the maximum number of bytes to read.
063     * @return     the total number of bytes read into the buffer, or
064     *             {@code -1} if there is no more data because the end of
065     *             the stream has been reached.
066     * @throws  IOException  if an I/O error occurs.
067     */
068    int read(byte[] b, int off, int len) throws IOException;
069
070    /**
071     * Reads some number of bytes from the session buffer and stores them into
072     * the buffer array {@code b}. The number of bytes actually read is
073     * returned as an integer.  This method blocks until input data is
074     * available, end of file is detected, or an exception is thrown.
075     *
076     * @param      b   the buffer into which the data is read.
077     * @return     the total number of bytes read into the buffer, or
078     *             {@code -1} is there is no more data because the end of
079     *             the stream has been reached.
080     * @throws  IOException  if an I/O error occurs.
081     */
082    int read(byte[] b) throws IOException;
083
084    /**
085     * Reads the next byte of data from this session buffer. The value byte is
086     * returned as an {@code int} in the range {@code 0} to
087     * {@code 255}. If no byte is available because the end of the stream
088     * has been reached, the value {@code -1} is returned. This method
089     * blocks until input data is available, the end of the stream is detected,
090     * or an exception is thrown.
091     *
092     * @return     the next byte of data, or {@code -1} if the end of the
093     *             stream is reached.
094     * @throws  IOException  if an I/O error occurs.
095     */
096    int read() throws IOException;
097
098    /**
099     * Reads a complete line of characters up to a line delimiter from this
100     * session buffer into the given line buffer. The number of chars actually
101     * read is returned as an integer. The line delimiter itself is discarded.
102     * If no char is available because the end of the stream has been reached,
103     * the value {@code -1} is returned. This method blocks until input
104     * data is available, end of file is detected, or an exception is thrown.
105     * <p>
106     * The choice of a char encoding and line delimiter sequence is up to the
107     * specific implementations of this interface.
108     *
109     * @param      buffer   the line buffer.
110     * @return     one line of characters
111     * @throws  IOException  if an I/O error occurs.
112     */
113    int readLine(CharArrayBuffer buffer) throws IOException;
114
115    /**
116     * Reads a complete line of characters up to a line delimiter from this
117     * session buffer. The line delimiter itself is discarded. If no char is
118     * available because the end of the stream has been reached,
119     * {@code null} is returned. This method blocks until input data is
120     * available, end of file is detected, or an exception is thrown.
121     * <p>
122     * The choice of a char encoding and line delimiter sequence is up to the
123     * specific implementations of this interface.
124     *
125     * @return HTTP line as a string
126     * @throws  IOException  if an I/O error occurs.
127     */
128    String readLine() throws IOException;
129
130    /** Blocks until some data becomes available in the session buffer or the
131     * given timeout period in milliseconds elapses. If the timeout value is
132     * {@code 0} this method blocks indefinitely.
133     *
134     * @param timeout in milliseconds.
135     * @return {@code true} if some data is available in the session
136     *   buffer or {@code false} otherwise.
137     * @throws  IOException  if an I/O error occurs.
138     *
139     * @deprecated (4.3) do not use. This function should be provided at the
140     *   connection level
141     */
142    @Deprecated
143    boolean isDataAvailable(int timeout) throws IOException;
144
145    /**
146     * Returns {@link HttpTransportMetrics} for this session buffer.
147     *
148     * @return transport metrics.
149     */
150    HttpTransportMetrics getMetrics();
151
152}