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

      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:
    `MessageDigestCalculatingInputStream`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `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 pProxy)` Creates a new ObservableInputStream for the given InputStream.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(ObservableInputStream.Observer pObserver)` Adds an Observer.
    `void` | `close()` Invokes the delegate's `close()` method.
    `void` | `consume()` Reads all data from the underlying `InputStream`, while notifying the observers.
    `protected List<ObservableInputStream.Observer>` | `getObservers()` Gets all currently registered observers.
    `protected void` | `noteClosed()` Notifies the observers by invoking `ObservableInputStream.Observer.finished()`.
    `protected void` | `noteDataByte(int pDataByte)` Notifies the observers by invoking `ObservableInputStream.Observer.data(int)` with the given arguments.
    `protected void` | `noteDataBytes(byte[] pBuffer, int pOffset, int pLength)` Notifies the observers by invoking `ObservableInputStream.Observer.data(byte[],int,int)` with the given arguments.
    `protected void` | `noteError(IOException pException)` 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 `read()` method.
    `int` | `read(byte[] pBuffer)` Invokes the delegate's `read(byte[])` method.
    `int` | `read(byte[] pBuffer, int pOffset, int pLength)` Invokes the delegate's `read(byte[], int, int)` method.
    `void` | `remove(ObservableInputStream.Observer pObserver)` 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, skip`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ObservableInputStream

          public ObservableInputStream(InputStream pProxy)

      Creates a new ObservableInputStream for the given InputStream.
      Parameters:
        `pProxy` - the input stream to proxy

  - ### Method Detail

    - #### add

          public void add(ObservableInputStream.Observer pObserver)

      Adds an Observer.
      Parameters:
        `pObserver` - the observer to add

    - #### remove

          public void remove(ObservableInputStream.Observer pObserver)

      Removes an Observer.
      Parameters:
        `pObserver` - the observer to remove

    - #### removeAllObservers

          public void removeAllObservers()

      Removes all Observers.

    - #### read

          public int read()
                   throws IOException

      Description copied from class: `ProxyInputStream`
      Invokes the delegate's `read()` method.
      Overrides:
        `read` in class `ProxyInputStream`
      Returns:
        the byte read or -1 if the end of stream
      Throws:
        `IOException` - if an I/O error occurs

    - #### read

          public int read(byte[] pBuffer)
                   throws IOException

      Description copied from class: `ProxyInputStream`
      Invokes the delegate's `read(byte[])` method.
      Overrides:
        `read` in class `ProxyInputStream`
      Parameters:
        `pBuffer` - the buffer to read the bytes into
      Returns:
        the number of bytes read or EOF if the end of stream
      Throws:
        `IOException` - if an I/O error occurs

    - #### read

          public int read(byte[] pBuffer,
                          int pOffset,
                          int pLength)
                   throws IOException

      Description copied from class: `ProxyInputStream`
      Invokes the delegate's `read(byte[], int, int)` method.
      Overrides:
        `read` in class `ProxyInputStream`
      Parameters:
        `pBuffer` - the buffer to read the bytes into
        `pOffset` - The start offset
        `pLength` - The number of bytes to read
      Returns:
        the number of bytes read or -1 if the end of stream
      Throws:
        `IOException` - if an I/O error occurs

    - #### noteDataBytes

          protected void noteDataBytes(byte[] pBuffer,
                                       int pOffset,
                                       int pLength)
                                throws IOException

      Notifies the observers by invoking `ObservableInputStream.Observer.data(byte[],int,int)` with the given arguments.
      Parameters:
        `pBuffer` - Passed to the observers.
        `pOffset` - Passed to the observers.
        `pLength` - Passed to the observers.
      Throws:
        `IOException` - Some observer has thrown an exception, which is being passed down.

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

    - #### noteDataByte

          protected void noteDataByte(int pDataByte)
                               throws IOException

      Notifies the observers by invoking `ObservableInputStream.Observer.data(int)` with the given arguments.
      Parameters:
        `pDataByte` - Passed to the observers.
      Throws:
        `IOException` - Some observer has thrown an exception, which is being passed down.

    - #### noteError

          protected void noteError(IOException pException)
                            throws IOException

      Notifies the observers by invoking `ObservableInputStream.Observer.error(IOException)` with the given argument.
      Parameters:
        `pException` - 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.

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

    - #### getObservers

          protected List<ObservableInputStream.Observer> getObservers()

      Gets all currently registered observers.
      Returns:
        a list of the currently registered observers

    - #### close

          public void close()
                     throws IOException

      Description copied from class: `ProxyInputStream`
      Invokes the delegate's `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.

Copyright © 2002–2020 The Apache Software Foundation. All rights reserved.