org.apache.commons.io.input

Class ObservableInputStream

java.lang.Object

java.io.InputStream

java.io.FilterInputStream

org.apache.commons.io.input.ProxyInputStream

org.apache.commons.io.input.ObservableInputStream

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

MessageDigestInputStream

public class ObservableInputStream
extends ProxyInputStream

The ObservableInputStream allows, that an InputStream may be consumed by other receivers, apart from the thread, which is reading it. The other consumers are implemented as instances of ObservableInputStream.Observer.

A typical application may be the generation of a MessageDigest on the fly.

Note: The ObservableInputStream is not thread safe, as instances of InputStream usually aren't. If you must access the stream from multiple threads, then synchronization, locking, or a similar means must be used.

See Also:

MessageDigestInputStream

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ObservableInputStream.AbstractBuilder<T extends ObservableInputStream.AbstractBuilder<T>> For subclassing builders from BoundedInputStream subclassses.
static class	ObservableInputStream.Builder Builds instances of ObservableInputStream.
static class	ObservableInputStream.Observer Abstracts observer callback for ObservableInputStreams.

Field Summary

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

Constructors

Constructor and Description
ObservableInputStream(InputStream inputStream) Constructs a new ObservableInputStream for the given InputStream.
ObservableInputStream(InputStream inputStream, ObservableInputStream.Observer... observers) Constructs a new ObservableInputStream for the given InputStream.
ObservableInputStream(ObservableInputStream.AbstractBuilder<?> builder)

Method Summary

Modifier and Type	Method and Description
void	add(ObservableInputStream.Observer observer) Adds an Observer.
void	close() Invokes the delegate's InputStream.close() method.
void	consume() Reads all data from the underlying InputStream, while notifying the observers.
List<ObservableInputStream.Observer>	getObservers() Gets a copy of currently registered observers.
protected void	noteClosed() Notifies the observers by invoking ObservableInputStream.Observer.finished().
protected void	noteDataByte(int value) Notifies the observers by invoking ObservableInputStream.Observer.data(int) with the given arguments.
protected void	noteDataBytes(byte[] buffer, int offset, int length) Notifies the observers by invoking ObservableInputStream.Observer.data(byte[],int,int) with the given arguments.
protected void	noteError(IOException exception) Notifies the observers by invoking ObservableInputStream.Observer.error(IOException) with the given argument.
protected void	noteFinished() Notifies the observers by invoking ObservableInputStream.Observer.finished().
int	read() Invokes the delegate's InputStream.read() method unless the stream is closed.
int	read(byte[] buffer) Invokes the delegate's InputStream.read(byte[]) method.
int	read(byte[] buffer, int offset, int length) Invokes the delegate's InputStream.read(byte[], int, int) method.
void	remove(ObservableInputStream.Observer observer) Removes an Observer.
void	removeAllObservers() Removes all Observers.

Methods inherited from class org.apache.commons.io.input.ProxyInputStream

afterRead, available, beforeRead, checkOpen, handleIOException, isClosed, mark, markSupported, reset, setReference, skip, unwrap

Methods inherited from class java.lang.Object

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

Constructor Detail

ObservableInputStream

public ObservableInputStream(InputStream inputStream)

Constructs a new ObservableInputStream for the given InputStream.

Parameters:

inputStream - the input stream to observe.

ObservableInputStream

public ObservableInputStream(InputStream inputStream,
                             ObservableInputStream.Observer... observers)

Constructs a new ObservableInputStream for the given InputStream.

Parameters:

inputStream - the input stream to observe.

observers - List of observer callbacks.

ObservableInputStream

ObservableInputStream(ObservableInputStream.AbstractBuilder<?> builder)
               throws IOException

Throws:

IOException

Method Detail

add

public void add(ObservableInputStream.Observer observer)

Adds an Observer.

Parameters:

observer - the observer to add.

close

public void close()
           throws IOException

Description copied from class: ProxyInputStream

Invokes the delegate's InputStream.close() method.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class ProxyInputStream

Throws:

IOException - if an I/O error occurs.

consume

public void consume()
             throws IOException

Reads all data from the underlying InputStream, while notifying the observers.

Throws:

IOException - The underlying InputStream, or either of the observers has thrown an exception.

getObservers

public List<ObservableInputStream.Observer> getObservers()

Gets a copy of currently registered observers.

Returns:

a copy of the list of currently registered observers.

noteClosed

protected void noteClosed()
                   throws IOException

Notifies the observers by invoking ObservableInputStream.Observer.finished().

Throws:

IOException - Some observer has thrown an exception, which is being passed down.

noteDataByte

protected void noteDataByte(int value)
                     throws IOException

Notifies the observers by invoking ObservableInputStream.Observer.data(int) with the given arguments.

Parameters:

value - Passed to the observers.

Throws:

IOException - Some observer has thrown an exception, which is being passed down.

noteDataBytes

protected void noteDataBytes(byte[] buffer,
                             int offset,
                             int length)
                      throws IOException

Notifies the observers by invoking ObservableInputStream.Observer.data(byte[],int,int) with the given arguments.

Parameters:

buffer - Passed to the observers.

offset - Passed to the observers.

length - Passed to the observers.

Throws:

IOException - Some observer has thrown an exception, which is being passed down.

noteError

protected void noteError(IOException exception)
                  throws IOException

Notifies the observers by invoking ObservableInputStream.Observer.error(IOException) with the given argument.

Parameters:

exception - Passed to the observers.

Throws:

IOException - Some observer has thrown an exception, which is being passed down. This may be the same exception, which has been passed as an argument.

noteFinished

protected void noteFinished()
                     throws IOException

Notifies the observers by invoking ObservableInputStream.Observer.finished().

Throws:

IOException - Some observer has thrown an exception, which is being passed down.

read

public int read()
         throws IOException

Description copied from class: ProxyInputStream

Invokes the delegate's InputStream.read() method unless the stream is closed.

Overrides:

read in class ProxyInputStream

Returns:

the byte read or EOF if we reached the end of stream.

Throws:

IOException - if an I/O error occurs.

read

public int read(byte[] buffer)
         throws IOException

Description copied from class: ProxyInputStream

Invokes the delegate's InputStream.read(byte[]) method.

Overrides:

read in class ProxyInputStream

Parameters:

buffer - the buffer to read the bytes into.

Returns:

the number of bytes read or EOF if we reached the end of stream.

Throws:

IOException -

• If the first byte cannot be read for any reason other than the end of the file,
• if the input stream has been closed, or
• if some other I/O error occurs.

read

public int read(byte[] buffer,
                int offset,
                int length)
         throws IOException

Description copied from class: ProxyInputStream

Invokes the delegate's InputStream.read(byte[], int, int) method.

Overrides:

read in class ProxyInputStream

Parameters:

buffer - the buffer to read the bytes into.

offset - The start offset.

length - The number of bytes to read.

Returns:

the number of bytes read or EOF if we reached the end of stream.

Throws:

IOException -

• If the first byte cannot be read for any reason other than the end of the file,
• if the input stream has been closed, or
• if some other I/O error occurs.

remove

public void remove(ObservableInputStream.Observer observer)

Removes an Observer.

Parameters:

observer - the observer to remove

removeAllObservers

public void removeAllObservers()

Removes all Observers.