Class ProcessMonitor


  • public class ProcessMonitor
    extends java.lang.Object

    This class is used to create and monitor the running of an operating system process.

    Class for running a native process in a separate thread.

     ProcessMonitor proc = new ProcessMonitor("/usr/bin/babel", "-ismiles", "-ocml");
     proc.setInput("CN(C)CCC1=CNC2=C1C=C(C=C2)CC3COC(=O)N3");
     ByteArrayOutputStream out = new ByteArrayOutputStream();
     proc.setOutputStream(out);
     proc.setErrorStream(System.err);
     proc.execsute();
     
    Author:
    Sam Adams
    • Constructor Summary

      Constructors 
      Constructor Description
      ProcessMonitor​(java.lang.String... command)
      Constructs a monitored process with the specified operating system program and arguments.
      ProcessMonitor​(java.util.List<java.lang.String> command)
      Constructs a monitored process with the specified operating system program and arguments.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void cancel()
      Cancel the process monitored by this object.
      int execute()
      Runs the process, waits for it to complete, and returns its exit status.
      byte[] getCachedError()
      Returns an array containing the last bytes the process monitored by this object has written to STDERR.
      byte[] getCachedOutput()
      Returns an array containing the last bytes the process monitored by this object has written to STDOUT.
      java.util.List<java.lang.String> getCommand()
      Returns this monitored process's operating system program and arguments.
      java.util.Map<java.lang.String,​java.lang.String> getEnvironment()  
      java.lang.Integer getExitValue()  
      java.lang.Throwable getFailCause()
      Returns any exception while the process is running, or null if no exception was thrown.
      boolean getRedirectErrorStream()  
      ProcessMonitor.ProcessState getState()
      Returns the current state of this process.
      long getTimeout​(java.util.concurrent.TimeUnit unit)  
      java.io.File getWorkingDirectory()
      Returns this monitored process's working directory.
      ProcessOutput runProcess()
      Runs the process, waits for it to complete, and returns its output.
      void setCommand​(java.lang.String... command)
      Sets this monitored process's operating system program and arguments.
      void setCommand​(java.util.List<java.lang.String> command)
      Sets this monitored process's operating system program and arguments.
      void setEnvironmentVariable​(java.lang.String key, java.lang.String value)  
      void setErrorTarget​(java.io.OutputStream stderr)
      Sets the OutputStream to which bytes written to the process' STDERR will be directed.
      void setInput​(byte[] input)
      Sets input for process.
      void setInput​(java.io.InputStream input)  
      void setInput​(java.lang.String input)
      Sets input for process.
      void setOutputTarget​(java.io.OutputStream stdout)
      Sets the OutputStream to which bytes written to the process' STDOUT will be directed.
      void setRedirectErrorStream​(boolean redirect)  
      void setTimeout​(long timeout, java.util.concurrent.TimeUnit timeoutUnit)
      Sets timeout after which process will be stopped.
      void setWorkingDirectory​(java.io.File dir)
      Sets this process' working directory.
      void start()
      Starts the new process to be monitored by this object.
      void unsetEnvironmentVariable​(java.lang.String key)  
      java.lang.Integer waitFor()
      Waits for the process to terminate, and returns the process' exit value.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • ProcessMonitor

        public ProcessMonitor​(java.lang.String... command)

        Constructs a monitored process with the specified operating system program and arguments. It is not checked whether command corresponds to a valid operating system command.

        Parameters:
        command - A string array containing the program and its arguments
        Throws:
        java.lang.NullPointerException - If the argument is null
      • ProcessMonitor

        public ProcessMonitor​(java.util.List<java.lang.String> command)

        Constructs a monitored process with the specified operating system program and arguments. It is not checked whether command corresponds to a valid operating system command.

        Parameters:
        command - A list containing the program and its arguments
        Throws:
        java.lang.NullPointerException - If the argument is null
    • Method Detail

      • getCommand

        public java.util.List<java.lang.String> getCommand()

        Returns this monitored process's operating system program and arguments. The returned list is a copy. Subsequent updates to the list will not be reflected in the state of this monitored process.

        Returns:
        This monitored process's program and its arguments
        See Also:
        ProcessBuilder.command()
      • setCommand

        public void setCommand​(java.lang.String... command)

        Sets this monitored process's operating system program and arguments. It is not checked whether command corresponds to a valid operating system command.

        Parameters:
        command - A string array containing the program and its arguments
        Throws:
        java.lang.NullPointerException - If the argument is null
        java.lang.IllegalStateException - If this monitored process has been started
        See Also:
        ProcessBuilder.command(String...)
      • setCommand

        public void setCommand​(java.util.List<java.lang.String> command)

        Sets this monitored process's operating system program and arguments. It is not checked whether command corresponds to a valid operating system command.

        Parameters:
        command - A list containing the program and its arguments
        command -
        Throws:
        java.lang.NullPointerException - If the argument is null
        java.lang.IllegalStateException - If this monitored process has been started
        See Also:
        ProcessBuilder.command(List)
      • getEnvironment

        public java.util.Map<java.lang.String,​java.lang.String> getEnvironment()
      • setEnvironmentVariable

        public void setEnvironmentVariable​(java.lang.String key,
                                           java.lang.String value)
      • unsetEnvironmentVariable

        public void unsetEnvironmentVariable​(java.lang.String key)
      • getWorkingDirectory

        public java.io.File getWorkingDirectory()

        Returns this monitored process's working directory. The returned value may be null -- this means to use the working directory of the current Java process, usually the directory named by the system property user.dir, as the working directory.

        Returns:
        This monitored process's working directory
        See Also:
        ProcessBuilder.directory()
      • setWorkingDirectory

        public void setWorkingDirectory​(java.io.File dir)

        Sets this process' working directory. The argument may be null -- this means to use the working directory of the current Java process, usually the directory named by the system property user.dir, as the working directory of the child process.

        Parameters:
        dir - The new working directory
        Throws:
        java.lang.IllegalStateException - If the process has been started
        See Also:
        ProcessBuilder.directory(File)
      • setInput

        public void setInput​(byte[] input)
        Sets input for process.
        Parameters:
        input -
        Throws:
        java.lang.NullPointerException - - if input is null.
        java.lang.IllegalStateException - - if process has been started, or input is already set.
      • setInput

        public void setInput​(java.lang.String input)
        Sets input for process. Makes call to setInput(final byte[] input), and will pass down any exception which that method throws.
        Parameters:
        input -
        Throws:
        java.lang.NullPointerException - - if input is null.
      • setInput

        public void setInput​(java.io.InputStream input)
      • setErrorTarget

        public void setErrorTarget​(java.io.OutputStream stderr)

        Sets the OutputStream to which bytes written to the process' STDERR will be directed. If this is set to null, then the output of the process will be discarded.

        Parameters:
        stderr -
        Throws:
        java.lang.IllegalStateException - If the process has been started
      • setOutputTarget

        public void setOutputTarget​(java.io.OutputStream stdout)

        Sets the OutputStream to which bytes written to the process' STDOUT will be directed. If this is set to null, then the output of the process will be discarded.

        Parameters:
        stdout -
        Throws:
        java.lang.IllegalStateException - If the process has been started
      • setRedirectErrorStream

        public void setRedirectErrorStream​(boolean redirect)
      • getRedirectErrorStream

        public boolean getRedirectErrorStream()
      • setTimeout

        public void setTimeout​(long timeout,
                               java.util.concurrent.TimeUnit timeoutUnit)
        Sets timeout after which process will be stopped. A timeout of 0 means wait forever.
        Parameters:
        timeout - - timeout in milliseconds.
        Throws:
        java.lang.IllegalStateException - - if thread has been started.
      • getTimeout

        public long getTimeout​(java.util.concurrent.TimeUnit unit)
      • getExitValue

        public java.lang.Integer getExitValue()
                                       throws java.util.concurrent.ExecutionException,
                                              java.util.concurrent.TimeoutException
        Returns:
        Throws:
        java.lang.IllegalStateException - If process has not been started, or is still running
        java.util.concurrent.ExecutionException - If this process threw an exception
        java.util.concurrent.TimeoutException - If this process timed out
        java.util.concurrent.CancellationException - If this process was cancelled
      • execute

        public int execute()
                    throws java.util.concurrent.ExecutionException,
                           java.lang.InterruptedException,
                           java.util.concurrent.TimeoutException
        Runs the process, waits for it to complete, and returns its exit status.
        Returns:
        Throws:
        java.lang.InterruptedException
        java.lang.IllegalStateException - - If process already started
        java.lang.InterruptedException - If this thread was interrupted before the process had finished.
        java.util.concurrent.TimeoutException
        java.util.concurrent.ExecutionException - If the process failed. This exception contains the output up to the point of failure, and the cause of failure.
      • runProcess

        public ProcessOutput runProcess()
                                 throws java.util.concurrent.ExecutionException,
                                        java.lang.InterruptedException,
                                        java.util.concurrent.TimeoutException
        Runs the process, waits for it to complete, and returns its output. This method captures the complete output (STDOUT/STDERR) from the process, along with its exit value. If the process produces a very large output then this may cause an OutOfMemoryError.
        Returns:
        Throws:
        java.lang.InterruptedException
        java.lang.IllegalStateException - - If process already started
        java.lang.InterruptedException - If this thread was interrupted before the process had finished.
        java.util.concurrent.TimeoutException
        java.util.concurrent.ExecutionException - If the process failed. This exception contains the output up to the point of failure, and the cause of failure.
      • waitFor

        public java.lang.Integer waitFor()
                                  throws java.util.concurrent.ExecutionException,
                                         java.util.concurrent.TimeoutException,
                                         java.lang.InterruptedException

        Waits for the process to terminate, and returns the process' exit value.

        Returns:
        The process' exit value
        Throws:
        java.lang.IllegalStateException - If the process has not been started
        java.util.concurrent.ExecutionException - If an error occurs while the process is executing
        java.util.concurrent.CancellationException - If the process is cancelled
        java.util.concurrent.TimeoutException - If the process timed out
        java.lang.InterruptedException - If this thread is interrupted while waiting for the process to finish
      • start

        public void start()

        Starts the new process to be monitored by this object.

        Throws:
        java.lang.IllegalStateException - If the process has been started.
      • cancel

        public void cancel()

        Cancel the process monitored by this object. If the process has already terminated, nothing is done.

        Throws:
        java.lang.IllegalStateException - If the process has not started
      • getCachedOutput

        public byte[] getCachedOutput()

        Returns an array containing the last bytes the process monitored by this object has written to STDOUT.

        Returns:
        The last bytes the process has written to STDOUT.
        Throws:
        java.lang.IllegalArgumentException - If the process has not started
      • getCachedError

        public byte[] getCachedError()

        Returns an array containing the last bytes the process monitored by this object has written to STDERR.

        Returns:
        The last bytes the process has written to STDERR.
        Throws:
        java.lang.IllegalArgumentException - If the process has not started
      • getFailCause

        public java.lang.Throwable getFailCause()
        Returns any exception while the process is running, or null if no exception was thrown.
        Returns: