Package 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`, `CountingInputStream`, `MarkShieldInputStream`, `ObservableInputStream`, `SwappedDataInputStream`, `TaggedInputStream`, `TeeInputStream`

public abstract class ProxyInputStream extends FilterInputStream
An input stream proxy which delegates to the wrapped input stream.

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

  Modifier and Type
  Method
  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.
  `void`
  `close()`
  Invokes the delegate's `InputStream.close()` method.
  `protected void`
  `handleIOException(IOException e)`
  Handles any IOExceptions thrown; by default, throws the given exception.
  `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 Details

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

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

- ## Method Details

  - ### 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)`.
    Since:
      2.0

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

  - ### close

    public void close() throws IOException
    Invokes the delegate's `InputStream.close()` method.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    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.
    Since:
      2.0

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

    Use with caution.

    Parameters:
      `in` - The input stream to set in `FilterInputStream.in`.
    Returns:
      `this` instance.
    Since:
      2.19.0

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

    Returns:
      the underlying `InputStream`.
    Since:
      2.16.0