Build 1.0_r1(from source)

org.apache.http.conn
Class EofSensorInputStream

java.lang.Object
  extended by java.io.InputStream
      extended by org.apache.http.conn.EofSensorInputStream
All Implemented Interfaces:
Closeable, 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
See Also:
EofSensorWatcher

Field Summary
protected  InputStream wrappedStream
          The wrapped input stream, while accessible.
 
Constructor Summary
EofSensorInputStream(InputStream in, EofSensorWatcher watcher)
          Creates a new EOF sensor.
 
Method Summary
 void abortConnection()
          Aborts this stream.
 int available()
          Returns a int representing then number of bytes that are available before this InputStream will block.
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()
          Close the InputStream.
protected  boolean isReadAllowed()
          Checks whether the underlying stream can be read from.
 int read()
          Reads a single byte from this InputStream and returns the result as an int.
 int read(byte[] b)
          Reads bytes from the Stream and stores them in byte array b.
 int read(byte[] b, int off, int len)
          Reads at most length bytes from the Stream and stores them in byte array b starting at offset.
 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 Detail

wrappedStream

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

Constructor Detail

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 Detail

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 InputStream and returns the result as an int. The low-order byte is returned or -1 of the end of stream was encountered. This abstract implementation must be provided by concrete subclasses.

Specified by:
read in class InputStream
Returns:
the byte read or -1 if end of stream.
Throws:
IOException - If the stream is already closed or another IOException occurs.

read

public int read(byte[] b,
                int off,
                int len)
         throws IOException
Description copied from class: InputStream
Reads at most length bytes from the Stream and stores them in byte array b starting at offset. Answer the number of bytes actually read or -1 if no bytes were read and end of stream was encountered.

Overrides:
read in class InputStream
Parameters:
b - the byte array in which to store the read bytes.
off - the offset in b to store the read bytes.
len - the maximum number of bytes to store in b.
Returns:
the number of bytes actually read or -1 if end of stream.
Throws:
IOException - If the stream is already closed or another IOException occurs.

read

public int read(byte[] b)
         throws IOException
Description copied from class: InputStream
Reads bytes from the Stream and stores them in byte array b. Answer the number of bytes actually read or -1 if no bytes were read and end of stream was encountered.

Overrides:
read in class InputStream
Parameters:
b - the byte array in which to store the read bytes.
Returns:
the number of bytes actually read or -1 if end of stream.
Throws:
IOException - If the stream is already closed or another IOException occurs.

available

public int available()
              throws IOException
Description copied from class: InputStream
Returns a int representing then number of bytes that are available before this InputStream will block. This method always returns 0. Subclasses should override and indicate the correct number of bytes available.

Overrides:
available in class InputStream
Returns:
the number of bytes available before blocking.
Throws:
IOException - If an error occurs in this InputStream.

close

public void close()
           throws IOException
Description copied from class: InputStream
Close the InputStream. Concrete implementations of this class should free any resources during close. This implementation does nothing.

Specified by:
close in interface Closeable
Overrides:
close in class InputStream
Throws:
IOException - If an error occurs attempting to close this InputStream.

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.

Build 1.0_r1(from source)

Please submit a feedback, bug or feature