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 `ObservableInputStream`s.

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

    All Methods Instance Methods Concrete Methods
    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.