Package org.apache.commons.exec

# Class PumpStreamHandler

java.lang.Object
org.apache.commons.exec.PumpStreamHandler

All Implemented Interfaces:
  `ExecuteStreamHandler`

public class PumpStreamHandler extends Object implements ExecuteStreamHandler
Copies standard output and error of sub-processes to standard output and error of the parent process. If output or error stream are set to null, any feedback from that stream will be lost.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PumpStreamHandler()`
  Constructs a new `PumpStreamHandler`.
  `PumpStreamHandler(OutputStream allOutputStream)`
  Constructs a new `PumpStreamHandler`.
  `PumpStreamHandler(OutputStream outputStream, OutputStream errorOutputStream)`
  Constructs a new `PumpStreamHandler`.
  `PumpStreamHandler(OutputStream outputStream, OutputStream errorOutputStream, InputStream inputStream)`
  Constructs a new `PumpStreamHandler`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `createProcessErrorPump(InputStream is, OutputStream os)`
  Create the pump to handle error output.
  `protected void`
  `createProcessOutputPump(InputStream is, OutputStream os)`
  Create the pump to handle process output.
  `protected Thread`
  `createPump(InputStream is, OutputStream os)`
  Creates a stream pumper to copy the given input stream to the given output stream.
  `protected Thread`
  `createPump(InputStream is, OutputStream os, boolean closeWhenExhausted)`
  Creates a stream pumper to copy the given input stream to the given output stream.
  `protected OutputStream`
  `getErr()`
  Gets the error stream.
  `protected OutputStream`
  `getOut()`
  Gets the output stream.
  `void`
  `setProcessErrorStream(InputStream is)`
  Sets the `InputStream` from which to read the standard error of the process.
  `void`
  `setProcessInputStream(OutputStream os)`
  Sets the `OutputStream` by means of which input can be sent to the process.
  `void`
  `setProcessOutputStream(InputStream is)`
  Sets the `InputStream` from which to read the standard output of the process.
  `void`
  `setStopTimeout(long timeout)`
  Deprecated.
  Use `setStopTimeout(Duration)`.
  `void`
  `setStopTimeout(Duration timeout)`
  Sets maximum time to wait until output streams are exhausted when `stop()` was called.
  `void`
  `start()`
  Starts the `Thread`s.
  `void`
  `stop()`
  Stops pumping the streams.
  `protected void`
  `stopThread(Thread thread, long timeoutMillis)`
  Stops a pumper thread.

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

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

- ## Constructor Details

  - ### PumpStreamHandler

    public PumpStreamHandler()
    Constructs a new `PumpStreamHandler`.

  - ### PumpStreamHandler

    public PumpStreamHandler(OutputStream allOutputStream)
    Constructs a new `PumpStreamHandler`.
    Parameters:
      `allOutputStream` - the output/error `OutputStream`. The `OutputStream` implementation must be thread-safe because the output and error reader threads will concurrently write to it.

  - ### PumpStreamHandler

    public PumpStreamHandler(OutputStream outputStream, OutputStream errorOutputStream)
    Constructs a new `PumpStreamHandler`.

    If the same `OutputStream` instance is used for output and error, then it must be thread-safe because the output and error reader threads will concurrently write to it.

    Parameters:
      `outputStream` - the output `OutputStream`.
      `errorOutputStream` - the error `OutputStream`.

  - ### PumpStreamHandler

    public PumpStreamHandler(OutputStream outputStream, OutputStream errorOutputStream, InputStream inputStream)
    Constructs a new `PumpStreamHandler`.

    If the same `OutputStream` instance is used for output and error, then it must be thread-safe because the output and error reader threads will concurrently write to it.

    Parameters:
      `outputStream` - the output `OutputStream`.
      `errorOutputStream` - the error `OutputStream`.
      `inputStream` - the input `InputStream`.

- ## Method Details

  - ### createProcessErrorPump

    protected void createProcessErrorPump(InputStream is, OutputStream os)
    Create the pump to handle error output.
    Parameters:
      `is` - the `InputStream`.
      `os` - the `OutputStream`.

  - ### createProcessOutputPump

    protected void createProcessOutputPump(InputStream is, OutputStream os)
    Create the pump to handle process output.
    Parameters:
      `is` - the `InputStream`.
      `os` - the `OutputStream`.

  - ### createPump

    protected Thread createPump(InputStream is, OutputStream os)
    Creates a stream pumper to copy the given input stream to the given output stream. When the 'os' is an PipedOutputStream we are closing 'os' afterwards to avoid an IOException ("Write end dead").
    Parameters:
      `is` - the input stream to copy from.
      `os` - the output stream to copy into.
    Returns:
      the stream pumper thread.

  - ### createPump

    protected Thread createPump(InputStream is, OutputStream os, boolean closeWhenExhausted)
    Creates a stream pumper to copy the given input stream to the given output stream.
    Parameters:
      `is` - the input stream to copy from.
      `os` - the output stream to copy into.
      `closeWhenExhausted` - close the output stream when the input stream is exhausted.
    Returns:
      the stream pumper thread.

  - ### getErr

    protected OutputStream getErr()
    Gets the error stream.
    Returns:
      `OutputStream`.

  - ### getOut

    protected OutputStream getOut()
    Gets the output stream.
    Returns:
      `OutputStream`.

  - ### setProcessErrorStream

    public void setProcessErrorStream(InputStream is)
    Sets the `InputStream` from which to read the standard error of the process.
    Specified by:
      `setProcessErrorStream` in interface `ExecuteStreamHandler`
    Parameters:
      `is` - the `InputStream`.

  - ### setProcessInputStream

    public void setProcessInputStream(OutputStream os)
    Sets the `OutputStream` by means of which input can be sent to the process.
    Specified by:
      `setProcessInputStream` in interface `ExecuteStreamHandler`
    Parameters:
      `os` - the `OutputStream`.

  - ### setProcessOutputStream

    public void setProcessOutputStream(InputStream is)
    Sets the `InputStream` from which to read the standard output of the process.
    Specified by:
      `setProcessOutputStream` in interface `ExecuteStreamHandler`
    Parameters:
      `is` - the `InputStream`.

  - ### setStopTimeout

    public void setStopTimeout(Duration timeout)
    Sets maximum time to wait until output streams are exhausted when `stop()` was called.
    Parameters:
      `timeout` - timeout or zero to wait forever (default).
    Since:
      1.4.0

  - ### setStopTimeout

    @Deprecated public void setStopTimeout(long timeout)
    Deprecated.
    Use `setStopTimeout(Duration)`.
    Sets maximum time to wait until output streams are exhausted when `stop()` was called.
    Parameters:
      `timeout` - timeout in milliseconds or zero to wait forever (default).

  - ### start

    public void start()
    Starts the `Thread`s.
    Specified by:
      `start` in interface `ExecuteStreamHandler`

  - ### stop

    public void stop() throws IOException
    Stops pumping the streams. When a timeout is specified it is not guaranteed that the pumper threads are cleanly terminated.
    Specified by:
      `stop` in interface `ExecuteStreamHandler`
    Throws:
      `IOException` - thrown when an I/O exception occurs.

  - ### stopThread

    protected void stopThread(Thread thread, long timeoutMillis)
    Stops a pumper thread. The implementation actually waits longer than specified in 'timeout' to detect if the timeout was indeed exceeded. If the timeout was exceeded an IOException is created to be thrown to the caller.
    Parameters:
      `thread` - the thread to be stopped.
      `timeoutMillis` - the time in ms to wait to join.