java.lang.Object | ||
↳ | java.io.InputStream | |
↳ | org.apache.http.conn.EofSensorInputStream |
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
.
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
wrappedStream | The wrapped input stream, while accessible. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Creates a new EOF sensor.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Aborts this stream.
| |||||||||||
Returns an estimated number of bytes that can be read or skipped without blocking for more
input.
| |||||||||||
Closes this stream.
| |||||||||||
Equivalent to
read(buffer, 0, buffer.length) . | |||||||||||
Reads a single byte from this stream and returns it as an integer in the
range from 0 to 255.
| |||||||||||
Reads up to
byteCount bytes from this stream and stores them in
the byte array buffer starting at byteOffset . | |||||||||||
Same as
close() . |
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Detects stream abort and notifies the watcher.
| |||||||||||
Detects stream close and notifies the watcher.
| |||||||||||
Detects EOF and notifies the watcher.
| |||||||||||
Checks whether the underlying stream can be read from.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.io.InputStream
| |||||||||||
From class
java.lang.Object
| |||||||||||
From interface
java.io.Closeable
| |||||||||||
From interface
java.lang.AutoCloseable
| |||||||||||
From interface
org.apache.http.conn.ConnectionReleaseTrigger
|
The wrapped input stream, while accessible.
The value changes to null
when the wrapped stream
becomes inaccessible.
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.
in | the wrapped stream |
---|---|
watcher | the watcher for events, or null for
auto-close behavior without notification
|
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.
IOException |
---|
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, 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.
IOException |
---|
Closes this stream. Concrete implementations of this class should free any resources during close. This implementation does nothing.
IOException |
---|
Equivalent to read(buffer, 0, buffer.length)
.
IOException |
---|
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.
IOException |
---|
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.
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.
IOException | in case of an IO problem on closing the underlying stream |
---|
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.
IOException | in case of an IO problem on closing the underlying stream |
---|
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.
eof | the result of the calling read operation. A negative value indicates that EOF is reached. |
---|
IOException | in case of an IO problem on closing the underlying stream |
---|
Checks whether the underlying stream can be read from.
true
if the underlying stream is accessible,
false
if this stream is in EOF mode and
detached from the underlying streamIOException | if this stream is already closed |
---|