Package org.apache.commons.exec

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

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.io.IOException caught
      The last exception being caught.
      private java.io.OutputStream errorOutputStream
      Error output stream.
      private java.lang.Thread errorThread
      Error thread.
      private java.io.InputStream inputStream
      Error input stream.
      private InputStreamPumper inputStreamPumper
      Pumper input stream.
      private java.lang.Thread inputThread
      Input thread.
      private java.io.OutputStream outputStream
      Output stream.
      private java.lang.Thread outputThread
      Output thread.
      private static java.time.Duration STOP_TIMEOUT_ADDITION
      Three seconds timeout.
      private java.time.Duration stopTimeout
      The timeout Duration the implementation waits when stopping the pumper threads.
      private java.util.concurrent.ThreadFactory threadFactory
      The thread factory.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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.
      private java.lang.Thread createSystemInPump​(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.io.OutputStream getErr()
      Gets the error stream.
      protected java.io.OutputStream getOut()
      Gets the output stream.
      (package private) java.time.Duration getStopTimeout()  
      void setProcessErrorStream​(java.io.InputStream is)
      Sets the InputStream from which to read the standard error of the process.
      void setProcessInputStream​(java.io.OutputStream os)
      Sets the OutputStream by means of which input can be sent to the process.
      void setProcessOutputStream​(java.io.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​(java.time.Duration timeout)
      Sets maximum time to wait until output streams are exhausted when stop() was called.
      void start()
      Starts the Threads.
      private void start​(java.lang.Thread thread)
      Starts the given Thread.
      void stop()
      Stops pumping the streams.
      private void stop​(java.lang.Thread thread, java.time.Duration timeout)
      Stops a pumper thread.
      protected void stopThread​(java.lang.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

    • Field Detail

      • STOP_TIMEOUT_ADDITION

        private static final java.time.Duration STOP_TIMEOUT_ADDITION
        Three seconds timeout.

      • outputThread

        private java.lang.Thread outputThread
        Output thread.

      • errorThread

        private java.lang.Thread errorThread
        Error thread.

      • inputThread

        private java.lang.Thread inputThread
        Input thread.

      • outputStream

        private final java.io.OutputStream outputStream
        Output stream.

      • errorOutputStream

        private final java.io.OutputStream errorOutputStream
        Error output stream.

      • inputStream

        private final java.io.InputStream inputStream
        Error input stream.

      • inputStreamPumper

        private InputStreamPumper inputStreamPumper
        Pumper input stream.

      • stopTimeout

        private java.time.Duration stopTimeout
        The timeout Duration the implementation waits when stopping the pumper threads.

      • caught

        private java.io.IOException caught
        The last exception being caught.

      • threadFactory

        private final java.util.concurrent.ThreadFactory threadFactory
        The thread factory.

    • Constructor Detail

      • PumpStreamHandler

        public PumpStreamHandler​(java.io.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​(java.io.OutputStream outputStream,
                         java.io.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​(java.io.OutputStream outputStream,
                         java.io.OutputStream errorOutputStream,
                         java.io.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.

      • PumpStreamHandler

        private PumpStreamHandler​(java.util.concurrent.ThreadFactory threadFactory,
                          java.io.OutputStream outputStream,
                          java.io.OutputStream errorOutputStream,
                          java.io.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 Detail

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

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

      • 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' afterward 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.

      • createSystemInPump

        private java.lang.Thread createSystemInPump​(java.io.InputStream is,
                                            java.io.OutputStream os)
        Creates a stream pumper to copy the given input stream to the given output stream.
        Parameters:
        is - the System.in input stream to copy from.
        os - the output stream to copy into.
        Returns:
        the stream pumper thread.

      • getErr

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

      • getOut

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

      • getStopTimeout

        java.time.Duration getStopTimeout()

      • setProcessErrorStream

        public void setProcessErrorStream​(java.io.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​(java.io.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​(java.io.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​(java.time.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

        private void start​(java.lang.Thread thread)
        Starts the given Thread.

      • stop

        public void stop()
          throws java.io.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:
        java.io.IOException - thrown when an I/O exception occurs.

      • stop

        private void stop​(java.lang.Thread thread,
                  java.time.Duration timeout)
        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.
        timeout - the time in ms to wait to join.

      • stopThread

        protected void stopThread​(java.lang.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.