Package org.apache.commons.io.output

# Class ProxyOutputStream

java.lang.Object
java.io.OutputStream
java.io.FilterOutputStream
org.apache.commons.io.output.ProxyOutputStream

All Implemented Interfaces:
  `Closeable`, `Flushable`, `AutoCloseable`

Direct Known Subclasses:
  `CloseShieldOutputStream`, `CountingOutputStream`, `FlushShieldOutputStream`, `TaggedOutputStream`, `TeeOutputStream`

public class ProxyOutputStream extends FilterOutputStream
An output stream proxy which delegates to the wrapped output stream.

See the protected methods for ways in which a subclass can easily decorate a stream with custom pre-, post- or error processing functionality.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ProxyOutputStream.Builder`
  Builds instances of `ProxyOutputStream`.

- ## Field Summary

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

  `out`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ProxyOutputStream(OutputStream delegate)`
  Constructs a new ProxyOutputStream.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `afterWrite(int n)`
  Invoked by the write methods after the proxied call has returned successfully.
  `protected void`
  `beforeWrite(int n)`
  Invoked by the write methods before the call is proxied.
  `void`
  `close()`
  Invokes the delegate's `close()` method.
  `void`
  `flush()`
  Invokes the delegate's `flush()` method.
  `protected void`
  `handleIOException(IOException e)`
  Handle any IOExceptions thrown.
  `ProxyOutputStream`
  `setReference(OutputStream out)`
  Sets the underlying output stream.
  `OutputStream`
  `unwrap()`
  Unwraps this instance by returning the underlying `OutputStream`.
  `void`
  `write(byte[] b)`
  Invokes the delegate's `write(byte[])` method.
  `void`
  `write(byte[] b, int off, int len)`
  Invokes the delegate's `write(byte[])` method.
  `void`
  `write(int b)`
  Invokes the delegate's `write(int)` method.
  `void`
  `writeRepeat(byte[] b, int off, int len, long repeat)`
  Invokes the delegate's `write(byte[])` method for the `repeat` count.
  `void`
  `writeRepeat(byte[] b, long repeat)`
  Invokes the delegate's `write(byte[])` method for the `repeat` count.
  `void`
  `writeRepeat(int b, long repeat)`
  Invokes the delegate's `write(int)` method.

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

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

- ## Constructor Details

  - ### ProxyOutputStream

    public ProxyOutputStream(OutputStream delegate)
    Constructs a new ProxyOutputStream.
    Parameters:
      `delegate` - the OutputStream to delegate to.

- ## Method Details

  - ### afterWrite

    protected void afterWrite(int n) throws IOException
    Invoked by the write methods after the proxied call has returned successfully. The number of bytes written (1 for the `write(int)` method, buffer length for `write(byte[])`, etc.) is given as an argument.

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

    Parameters:
      `n` - number of bytes written.
    Throws:
      `IOException` - if the post-processing fails.
    Since:
      2.0

  - ### beforeWrite

    protected void beforeWrite(int n) throws IOException
    Invoked by the write methods before the call is proxied. The number of bytes to be written (1 for the `write(int)` method, buffer length for `write(byte[])`, etc.) is given as an argument.

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

    Parameters:
      `n` - number of bytes to be written.
    Throws:
      `IOException` - if the pre-processing fails.
    Since:
      2.0

  - ### close

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

  - ### flush

    public void flush() throws IOException
    Invokes the delegate's `flush()` method.
    Specified by:
      `flush` in interface `Flushable`
    Overrides:
      `flush` in class `FilterOutputStream`
    Throws:
      `IOException` - if an I/O error occurs.

  - ### handleIOException

    protected void handleIOException(IOException e) throws IOException
    Handle any IOExceptions thrown.

    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

  - ### setReference

    public ProxyOutputStream setReference(OutputStream out)
    Sets the underlying output stream.

    Use with caution.

    Parameters:
      `out` - the underlying output stream.
    Returns:
      `this` instance.
    Since:
      2.19.0

  - ### unwrap

    public OutputStream unwrap()
    Unwraps this instance by returning the underlying `OutputStream`.

    Use with caution.

    Returns:
      the underlying `OutputStream`.
    Since:
      2.22.0

  - ### write

    public void write(byte[] b) throws IOException
    Invokes the delegate's `write(byte[])` method.
    Overrides:
      `write` in class `FilterOutputStream`
    Parameters:
      `b` - the bytes to write.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### write

    public void write(byte[] b, int off, int len) throws IOException
    Invokes the delegate's `write(byte[])` method.
    Overrides:
      `write` in class `FilterOutputStream`
    Parameters:
      `b` - the bytes to write.
      `off` - The start offset.
      `len` - The number of bytes to write.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### write

    public void write(int b) throws IOException
    Invokes the delegate's `write(int)` method.
    Overrides:
      `write` in class `FilterOutputStream`
    Parameters:
      `b` - the byte to write.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### writeRepeat

    public void writeRepeat(byte[] b, int off, int len, long repeat) throws IOException
    Invokes the delegate's `write(byte[])` method for the `repeat` count.
    Parameters:
      `b` - the bytes to write.
      `off` - The start offset.
      `len` - The number of bytes to write.
      `repeat` - How many times to write the bytes in `b`.
    Throws:
      `IOException` - if an I/O error occurs.
    Since:
      2.21.0

  - ### writeRepeat

    public void writeRepeat(byte[] b, long repeat) throws IOException
    Invokes the delegate's `write(byte[])` method for the `repeat` count.
    Parameters:
      `b` - the bytes to write.
      `repeat` - How many times to write the bytes in `b`.
    Throws:
      `IOException` - if an I/O error occurs.
    Since:
      2.21.0

  - ### writeRepeat

    public void writeRepeat(int b, long repeat) throws IOException
    Invokes the delegate's `write(int)` method.
    Parameters:
      `b` - the byte to write.
      `repeat` - How many times to write the byte in `b`.
    Throws:
      `IOException` - if an I/O error occurs.
    Since:
      2.21.0