org.apache.commons.io.input

## Class ProxyInputStream

- java.lang.Object
- - java.io.InputStream
  - - java.io.FilterInputStream
    - - org.apache.commons.io.input.ProxyInputStream

- All Implemented Interfaces:
    Closeable, AutoCloseable
  Direct Known Subclasses:
    AutoCloseInputStream, BOMInputStream, BoundedInputStream, CloseShieldInputStream, org.apache.commons.io.input.CountingInputStream, MarkShieldInputStream, ObservableInputStream, SwappedDataInputStream, TaggedInputStream, TeeInputStream

      public abstract class ProxyInputStream
      extends FilterInputStream

  A proxy stream which acts as a `FilterInputStream`, by passing all method calls on to the proxied stream, not changing which methods are called.

  It is an alternative base class to `FilterInputStream` to increase reusability, because `FilterInputStream` changes the methods being called, such as read(byte[]) to read(byte[], int, int).

  In addition, this class allows you to:

  - notify a subclass that n bytes are about to be read through `beforeRead(int)`
  - notify a subclass that n bytes were read through `afterRead(int)`
  - notify a subclass that an exception was caught through `handleIOException(IOException)`
  - `unwrap()` itself

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `ProxyInputStream.AbstractBuilder<T,B extends AbstractStreamBuilder<T,B>>` Abstracts builder properties for subclasses.

  - ### Field Summary

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

      `in`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `ProxyInputStream(InputStream proxy)` Constructs a new ProxyInputStream.
    `protected` | `ProxyInputStream(InputStream proxy, ProxyInputStream.AbstractBuilder<?,?> builder)` Constructs a new ProxyInputStream.
    `protected` | `ProxyInputStream(ProxyInputStream.AbstractBuilder<?,?> builder)` Constructs a new ProxyInputStream.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `afterRead(int n)` Called by the `read` methods after the proxied call has returned successfully.
    `int` | `available()` Invokes the delegate's `InputStream.available()` method.
    `protected void` | `beforeRead(int n)` Invoked by the `read` methods before the call is proxied.
    `(package private) void` | `checkOpen()` Checks if this instance is closed and throws an IOException if so.
    `void` | `close()` Invokes the delegate's `InputStream.close()` method.
    `protected void` | `handleIOException(IOException e)` Handles any IOExceptions thrown; by default, throws the given exception.
    `(package private) boolean` | `isClosed()` Tests whether this instance is closed.
    `void` | `mark(int readLimit)` Invokes the delegate's `InputStream.mark(int)` method.
    `boolean` | `markSupported()` Invokes the delegate's `InputStream.markSupported()` method.
    `int` | `read()` Invokes the delegate's `InputStream.read()` method unless the stream is closed.
    `int` | `read(byte[] b)` Invokes the delegate's `InputStream.read(byte[])` method.
    `int` | `read(byte[] b, int off, int len)` Invokes the delegate's `InputStream.read(byte[], int, int)` method.
    `void` | `reset()` Invokes the delegate's `InputStream.reset()` method.
    `ProxyInputStream` | `setReference(InputStream in)` Sets the underlying input stream.
    `long` | `skip(long n)` Invokes the delegate's `InputStream.skip(long)` method.
    `InputStream` | `unwrap()` Unwraps this instance by returning the underlying `InputStream`.

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

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

- - ### Constructor Detail

    - #### ProxyInputStream

          public ProxyInputStream(InputStream proxy)

      Constructs a new ProxyInputStream.
      Parameters:
        `proxy` - the InputStream to proxy.

    - #### ProxyInputStream

          protected ProxyInputStream(InputStream proxy,
                                     ProxyInputStream.AbstractBuilder<?,?> builder)

      Constructs a new ProxyInputStream.
      Parameters:
        `proxy` - the InputStream to proxy.
        `builder` - How to build an instance.

    - #### ProxyInputStream

          protected ProxyInputStream(ProxyInputStream.AbstractBuilder<?,?> builder)
                              throws IOException

      Constructs a new ProxyInputStream.
      Parameters:
        `builder` - How to build an instance.
      Throws:
        `IOException` - if an I/O error occurs.

  - ### Method Detail

    - #### afterRead

          protected void afterRead(int n)
                            throws IOException

      Called by the `read` methods after the proxied call has returned successfully. The argument is the number of bytes returned to the caller or `EOF` if the end of stream was reached.

      The default delegates to the consumer given to `ProxyInputStream.AbstractBuilder.setAfterRead(IOIntConsumer)`.

      Alternatively, a subclasses can override this method to add post-processing functionality without having to override all the read methods.

      Note this method is not called from `skip(long)` or `reset()`. You need to explicitly override those methods if you want to add post-processing steps also to them.

      Parameters:
        `n` - number of bytes read, or `EOF` if the end of stream was reached.
      Throws:
        `IOException` - Thrown by a subclass or the consumer given to `ProxyInputStream.AbstractBuilder.setAfterRead(IOIntConsumer)`.

    - #### available

          public int available()
                        throws IOException

      Invokes the delegate's `InputStream.available()` method.
      Overrides:
        `available` in class `FilterInputStream`
      Returns:
        the number of available bytes, 0 if the stream is closed.
      Throws:
        `IOException` - if an I/O error occurs.

    - #### beforeRead

          protected void beforeRead(int n)
                             throws IOException

      Invoked by the `read` methods before the call is proxied. The number of bytes that the caller wanted to read (1 for the `read()` method, buffer length for `read(byte[])`, etc.) is given as an argument.

      Subclasses can override this method to add common pre-processing functionality without having to override all the read methods. The default implementation does nothing.

      Note this method is not called from `skip(long)` or `reset()`. You need to explicitly override those methods if you want to add pre-processing steps also to them.

      Parameters:
        `n` - number of bytes that the caller asked to be read.
      Throws:
        `IOException` - if the pre-processing fails in a subclass.

    - #### checkOpen

          void checkOpen()
                  throws IOException

      Checks if this instance is closed and throws an IOException if so.
      Throws:
        `IOException` - if this instance is closed.

    - #### close

          public void close()
                     throws IOException

      Invokes the delegate's `InputStream.close()` method.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Overrides:
        `close` in class `FilterInputStream`
      Throws:
        `IOException` - if an I/O error occurs.

    - #### handleIOException

          protected void handleIOException(IOException e)
                                    throws IOException

      Handles any IOExceptions thrown; by default, throws the given exception.

      This method provides a point to implement custom exception handling. The default behavior is to re-throw the exception.

      Parameters:
        `e` - The IOException thrown.
      Throws:
        `IOException` - if an I/O error occurs.

    - #### isClosed

          boolean isClosed()

      Tests whether this instance is closed.
      Returns:
        whether this instance is closed.

    - #### mark

          public void mark(int readLimit)

      Invokes the delegate's `InputStream.mark(int)` method.
      Overrides:
        `mark` in class `FilterInputStream`
      Parameters:
        `readLimit` - read ahead limit.

    - #### markSupported

          public boolean markSupported()

      Invokes the delegate's `InputStream.markSupported()` method.
      Overrides:
        `markSupported` in class `FilterInputStream`
      Returns:
        `true` if this stream instance supports the mark and reset methods; `false` otherwise.
      See Also:
        `mark(int)`, `reset()`

    - #### read

          public int read()
                   throws IOException

      Invokes the delegate's `InputStream.read()` method unless the stream is closed.
      Overrides:
        `read` in class `FilterInputStream`
      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[] b)
                   throws IOException

      Invokes the delegate's `InputStream.read(byte[])` method.
      Overrides:
        `read` in class `FilterInputStream`
      Parameters:
        `b` - 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[] b,
                          int off,
                          int len)
                   throws IOException

      Invokes the delegate's `InputStream.read(byte[], int, int)` method.
      Overrides:
        `read` in class `FilterInputStream`
      Parameters:
        `b` - the buffer to read the bytes into.
        `off` - The start offset.
        `len` - 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.

    - #### reset

          public void reset()
                     throws IOException

      Invokes the delegate's `InputStream.reset()` method.
      Overrides:
        `reset` in class `FilterInputStream`
      Throws:
        `IOException` - if this stream has not been marked or if the mark has been invalidated.

    - #### setReference

          public ProxyInputStream setReference(InputStream in)

      Sets the underlying input stream.
      Parameters:
        `in` - The input stream to set in `FilterInputStream.in`.
      Returns:
        this instance.

    - #### skip

          public long skip(long n)
                    throws IOException

      Invokes the delegate's `InputStream.skip(long)` method.
      Overrides:
        `skip` in class `FilterInputStream`
      Parameters:
        `n` - the number of bytes to skip.
      Returns:
        the actual number of bytes skipped.
      Throws:
        `IOException` - if the stream does not support seek, or if some other I/O error occurs.

    - #### unwrap

          public InputStream unwrap()

      Unwraps this instance by returning the underlying `InputStream`.

      Use with caution; useful to query the underlying `InputStream`.

      Returns:
        the underlying `InputStream`.