PumpStreamHandler
Date: 2017-01-22

org.apache.commons.exec

## Class PumpStreamHandler

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

- All Implemented Interfaces:
    ExecuteStreamHandler

      public class PumpStreamHandler
      extends java.lang.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 and Description
    `PumpStreamHandler()` Construct a new `PumpStreamHandler`.
    `PumpStreamHandler(java.io.OutputStream outAndErr)` Construct a new `PumpStreamHandler`.
    `PumpStreamHandler(java.io.OutputStream out, java.io.OutputStream err)` Construct a new `PumpStreamHandler`.
    `PumpStreamHandler(java.io.OutputStream out, java.io.OutputStream err, java.io.InputStream input)` Construct a new `PumpStreamHandler`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `createProcessErrorPump(java.io.InputStream is, java.io.OutputStream os)` Create the pump to handle error output.
    `protected void` | `createProcessOutputPump(java.io.InputStream is, java.io.OutputStream os)` Create the pump to handle process output.
    `protected java.lang.Thread` | `createPump(java.io.InputStream is, java.io.OutputStream os)` Creates a stream pumper to copy the given input stream to the given output stream.
    `protected java.lang.Thread` | `createPump(java.io.InputStream is, java.io.OutputStream os, boolean closeWhenExhausted)` Creates a stream pumper to copy the given input stream to the given output stream.
    `protected java.io.OutputStream` | `getErr()` Get the error stream.
    `protected java.io.OutputStream` | `getOut()` Get the output stream.
    `void` | `setProcessErrorStream(java.io.InputStream is)` Set the `InputStream` from which to read the standard error of the process.
    `void` | `setProcessInputStream(java.io.OutputStream os)` Set the `OutputStream` by means of which input can be sent to the process.
    `void` | `setProcessOutputStream(java.io.InputStream is)` Set the `InputStream` from which to read the standard output of the process.
    `void` | `setStopTimeout(long timeout)` Set maximum time to wait until output streams are exchausted when `stop()` was called.
    `void` | `start()` Start the `Thread`s.
    `void` | `stop()` Stop pumping the streams.
    `protected void` | `stopThread(java.lang.Thread thread, long timeout)` Stopping a pumper thread.

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

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

- - ### Constructor Detail

    - #### PumpStreamHandler

          public PumpStreamHandler()

      Construct a new `PumpStreamHandler`.

    - #### PumpStreamHandler

          public PumpStreamHandler(java.io.OutputStream outAndErr)

      Construct a new `PumpStreamHandler`.
      Parameters:
        `outAndErr` - the output/error `OutputStream`.

    - #### PumpStreamHandler

          public PumpStreamHandler(java.io.OutputStream out,
                           java.io.OutputStream err)

      Construct a new `PumpStreamHandler`.
      Parameters:
        `out` - the output `OutputStream`.
        `err` - the error `OutputStream`.

    - #### PumpStreamHandler

          public PumpStreamHandler(java.io.OutputStream out,
                           java.io.OutputStream err,
                           java.io.InputStream input)

      Construct a new `PumpStreamHandler`.
      Parameters:
        `out` - the output `OutputStream`.
        `err` - the error `OutputStream`.
        `input` - the input `InputStream`.

  - ### Method Detail

    - #### setStopTimeout

          public void setStopTimeout(long timeout)

      Set maximum time to wait until output streams are exchausted when `stop()` was called.
      Parameters:
        `timeout` - timeout in milliseconds or zero to wait forever (default)

    - #### setProcessOutputStream

          public void setProcessOutputStream(java.io.InputStream is)

      Set the `InputStream` from which to read the standard output of the process.
      Specified by:
        `setProcessOutputStream` in interface `ExecuteStreamHandler`
      Parameters:
        `is` - the `InputStream`.

    - #### setProcessErrorStream

          public void setProcessErrorStream(java.io.InputStream is)

      Set 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(java.io.OutputStream os)

      Set the `OutputStream` by means of which input can be sent to the process.
      Specified by:
        `setProcessInputStream` in interface `ExecuteStreamHandler`
      Parameters:
        `os` - the `OutputStream`.

    - #### start

          public void start()

      Start the `Thread`s.
      Specified by:
        `start` in interface `ExecuteStreamHandler`

    - #### stop

          public void stop()
                    throws java.io.IOException

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

    - #### getErr

          protected java.io.OutputStream getErr()

      Get the error stream.
      Returns:
        `OutputStream`.

    - #### getOut

          protected java.io.OutputStream getOut()

      Get the output stream.
      Returns:
        `OutputStream`.

    - #### createProcessOutputPump

          protected void createProcessOutputPump(java.io.InputStream is,
                                     java.io.OutputStream os)

      Create the pump to handle process output.
      Parameters:
        `is` - the `InputStream`.
        `os` - the `OutputStream`.

    - #### createProcessErrorPump

          protected void createProcessErrorPump(java.io.InputStream is,
                                    java.io.OutputStream os)

      Create the pump to handle error output.
      Parameters:
        `is` - the `InputStream`.
        `os` - the `OutputStream`.

    - #### createPump

          protected java.lang.Thread createPump(java.io.InputStream is,
                                    java.io.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 java.lang.Thread createPump(java.io.InputStream is,
                                    java.io.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

    - #### stopThread

          protected void stopThread(java.lang.Thread thread,
                        long timeout)

      Stopping 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
        `timeout` - the time in ms to wait to join