Package org.apache.http.conn

Class EofSensorInputStream

java.lang.Object
java.io.InputStream
org.apache.http.conn.EofSensorInputStream
All Implemented Interfaces:
Closeable, AutoCloseable, ConnectionReleaseTrigger
public class EofSensorInputStream
extends InputStream
implements ConnectionReleaseTrigger
A stream wrapper that triggers actions on close() and EOF. Primarily used to auto-release an underlying connection when the response body is consumed or no longer needed.

This class is based on AutoCloseInputStream in HttpClient 3.1, but has notable differences. It does not allow mark/reset, distinguishes different kinds of event, and does not always close the underlying stream on EOF. That decision is left to the watcher.

Since:
4.0
Version:
$Revision: 672367 $
Author:
Roland Weber, Ortwin Glueck, Eric Johnson, Mike Bowler
See Also:
EofSensorWatcher

  • Field Summary

    Fields
    Modifier and Type Field Description
    protected InputStream wrappedStream
    The wrapped input stream, while accessible.

  • Constructor Summary

    Constructors
    Constructor Description
    EofSensorInputStream​(InputStream in, EofSensorWatcher watcher)
    Creates a new EOF sensor.

  • Method Summary

    Modifier and Type Method Description
    void abortConnection()
    Aborts this stream.
    int available()
    Returns an estimated number of bytes that can be read or skipped without blocking for more input.
    protected void checkAbort()
    Detects stream abort and notifies the watcher.
    protected void checkClose()
    Detects stream close and notifies the watcher.
    protected void checkEOF​(int eof)
    Detects EOF and notifies the watcher.
    void close()
    Closes this stream.
    protected boolean isReadAllowed()
    Checks whether the underlying stream can be read from.
    int read()
    Reads a single byte from this stream and returns it as an integer in the range from 0 to 255.
    int read​(byte[] b)
    Equivalent to read(buffer, 0, buffer.length).
    int read​(byte[] b, int off, int len)
    Reads up to byteCount bytes from this stream and stores them in the byte array buffer starting at byteOffset.
    void releaseConnection()
    Same as close().

    Methods inherited from class java.io.InputStream

    mark, markSupported, reset, skip

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • wrappedStream

      protected InputStream wrappedStream
      The wrapped input stream, while accessible. The value changes to null when the wrapped stream becomes inaccessible.

  • Constructor Details

    • EofSensorInputStream

      public EofSensorInputStream​(InputStream in, EofSensorWatcher watcher)
      Creates a new EOF sensor. If no watcher is passed, the underlying stream will simply be closed when EOF is detected or close is called. Otherwise, the watcher decides whether the underlying stream should be closed before detaching from it.
      Parameters:
      in - the wrapped stream
      watcher - the watcher for events, or null for auto-close behavior without notification

  • Method Details

    • isReadAllowed

      protected boolean isReadAllowed() throws IOException
      Checks whether the underlying stream can be read from.
      Returns:
      true if the underlying stream is accessible, false if this stream is in EOF mode and detached from the underlying stream
      Throws:
      IOException - if this stream is already closed

    • read

      public int read() throws IOException
      Description copied from class: InputStream
      Reads a single byte from this stream and returns it as an integer in the range from 0 to 255. Returns -1 if the end of the stream has been reached. Blocks until one byte has been read, the end of the source stream is detected or an exception is thrown.
      Specified by:
      read in class InputStream
      Throws:
      IOException - if the stream is closed or another IOException occurs.

    • read

      public int read​(byte[] b, int off, int len) throws IOException
      Description copied from class: InputStream
      Reads up to byteCount bytes from this stream and stores them in the byte array buffer starting at byteOffset. Returns the number of bytes actually read or -1 if the end of the stream has been reached.
      Overrides:
      read in class InputStream
      Throws:
      IOException - if the stream is closed or another IOException occurs.

    • read

      public int read​(byte[] b) throws IOException
      Description copied from class: InputStream
      Equivalent to read(buffer, 0, buffer.length).
      Overrides:
      read in class InputStream
      Throws:
      IOException

    • available

      public int available() throws IOException
      Description copied from class: InputStream
      Returns an estimated number of bytes that can be read or skipped without blocking for more input.

      Note that this method provides such a weak guarantee that it is not very useful in practice.

      Firstly, the guarantee is "without blocking for more input" rather than "without blocking": a read may still block waiting for I/O to complete — the guarantee is merely that it won't have to wait indefinitely for data to be written. The result of this method should not be used as a license to do I/O on a thread that shouldn't be blocked.

      Secondly, the result is a conservative estimate and may be significantly smaller than the actual number of bytes available. In particular, an implementation that always returns 0 would be correct. In general, callers should only use this method if they'd be satisfied with treating the result as a boolean yes or no answer to the question "is there definitely data ready?".

      Thirdly, the fact that a given number of bytes is "available" does not guarantee that a read or skip will actually read or skip that many bytes: they may read or skip fewer.

      It is particularly important to realize that you must not use this method to size a container and assume that you can read the entirety of the stream without needing to resize the container. Such callers should probably write everything they read to a ByteArrayOutputStream and convert that to a byte array. Alternatively, if you're reading from a file, File.length() returns the current length of the file (though assuming the file's length can't change may be incorrect, reading a file is inherently racy).

      The default implementation of this method in InputStream always returns 0. Subclasses should override this method if they are able to indicate the number of bytes available.

      Overrides:
      available in class InputStream
      Returns:
      the estimated number of bytes available
      Throws:
      IOException - if this stream is closed or an error occurs

    • close

      public void close() throws IOException
      Description copied from class: InputStream
      Closes this stream. Concrete implementations of this class should free any resources during close. This implementation does nothing.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close in class InputStream
      Throws:
      IOException - if an error occurs while closing this stream.

    • checkEOF

      protected void checkEOF​(int eof) throws IOException
      Detects EOF and notifies the watcher. This method should only be called while the underlying stream is still accessible. Use isReadAllowed to check that condition.
      If EOF is detected, the watcher will be notified and this stream is detached from the underlying stream. This prevents multiple notifications from this stream.
      Parameters:
      eof - the result of the calling read operation. A negative value indicates that EOF is reached.
      Throws:
      IOException - in case of an IO problem on closing the underlying stream

    • checkClose

      protected void checkClose() throws IOException
      Detects stream close and notifies the watcher. There's not much to detect since this is called by close. The watcher will only be notified if this stream is closed for the first time and before EOF has been detected. This stream will be detached from the underlying stream to prevent multiple notifications to the watcher.
      Throws:
      IOException - in case of an IO problem on closing the underlying stream

    • checkAbort

      protected void checkAbort() throws IOException
      Detects stream abort and notifies the watcher. There's not much to detect since this is called by abortConnection. The watcher will only be notified if this stream is aborted for the first time and before EOF has been detected or the stream has been closed gracefully. This stream will be detached from the underlying stream to prevent multiple notifications to the watcher.
      Throws:
      IOException - in case of an IO problem on closing the underlying stream

    • releaseConnection

      public void releaseConnection() throws IOException
      Same as close().
      Specified by:
      releaseConnection in interface ConnectionReleaseTrigger
      Throws:
      IOException - in case of an IO problem. The connection will be released anyway.

    • abortConnection

      public void abortConnection() throws IOException
      Aborts this stream. This is a special version of close() which prevents re-use of the underlying connection, if any. Calling this method indicates that there should be no attempt to read until the end of the stream.
      Specified by:
      abortConnection in interface ConnectionReleaseTrigger
      Throws:
      IOException - in case of an IO problem. The connection will be released anyway.