Package 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:
  `MessageDigestCalculatingInputStream`, `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
  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 `ObservableInputStream`s.

- ## Field Summary

  ### Fields inherited from class java.io.FilterInputStream

  `in`

- ## Constructor Summary

  Constructors
  Constructor
  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.

- ## Method Summary

  Modifier and Type
  Method
  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, handleIOException, 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 Details

  - ### 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.
    Since:
      2.9.0

- ## Method Details

  - ### 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 `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    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.
    Since:
      2.9.0

  - ### 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.