Class DefaultExecutor

  • All Implemented Interfaces:
    Executor
    Direct Known Subclasses:
    DaemonExecutor

    public class DefaultExecutor
    extends java.lang.Object
    implements Executor
    The default class to start a subprocess. The implementation allows to
    • set a current working directory for the subprocess
    • provide a set of environment variables passed to the subprocess
    • capture the subprocess output of stdout and stderr using an ExecuteStreamHandler
    • kill long-running processes using an ExecuteWatchdog
    • define a set of expected exit values
    • terminate any started processes when the main process is terminating using a ProcessDestroyer
    The following example shows the basic usage:
     Executor exec = new DefaultExecutor();
     CommandLine cl = new CommandLine("ls -l");
     int exitvalue = exec.execute(cl);
     
    Version:
    $Id: DefaultExecutor.java 1636056 2014-11-01 21:12:52Z ggregory $
    • Constructor Summary

      Constructors 
      Constructor Description
      DefaultExecutor()
      Default constructor creating a default PumpStreamHandler and sets the working directory of the subprocess to the current working directory.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void closeProcessStreams​(java.lang.Process process)
      Close the streams belonging to the given Process.
      protected java.lang.Thread createThread​(java.lang.Runnable runnable, java.lang.String name)
      Factory method to create a thread waiting for the result of an asynchronous execution.
      int execute​(CommandLine command)
      Methods for starting synchronous execution.
      int execute​(CommandLine command, java.util.Map<java.lang.String,​java.lang.String> environment)
      Methods for starting synchronous execution.
      void execute​(CommandLine command, java.util.Map<java.lang.String,​java.lang.String> environment, ExecuteResultHandler handler)
      Methods for starting asynchronous execution.
      void execute​(CommandLine command, ExecuteResultHandler handler)
      Methods for starting asynchronous execution.
      private int executeInternal​(CommandLine command, java.util.Map<java.lang.String,​java.lang.String> environment, java.io.File dir, ExecuteStreamHandler streams)
      Execute an internal process.
      private java.io.IOException getExceptionCaught()
      Get the first IOException being thrown.
      protected java.lang.Thread getExecutorThread()
      Get the worker thread being used for asynchronous execution.
      ProcessDestroyer getProcessDestroyer()
      Set the handler for cleanup of started processes if the main process is going to terminate.
      ExecuteStreamHandler getStreamHandler()
      Get the StreamHandler used for providing input and retrieving the output.
      ExecuteWatchdog getWatchdog()
      Get the watchdog used to kill of processes running, typically, too long time.
      java.io.File getWorkingDirectory()
      Get the working directory of the created process.
      boolean isFailure​(int exitValue)
      Checks whether exitValue signals a failure.
      protected java.lang.Process launch​(CommandLine command, java.util.Map<java.lang.String,​java.lang.String> env, java.io.File dir)
      Creates a process that runs a command.
      private void setExceptionCaught​(java.io.IOException e)
      Keep track of the first IOException being thrown.
      void setExitValue​(int value)
      Define the exitValue of the process to be considered successful.
      void setExitValues​(int[] values)
      Define a list of exitValue of the process to be considered successful.
      void setProcessDestroyer​(ProcessDestroyer processDestroyer)
      Get the handler for cleanup of started processes if the main process is going to terminate.
      void setStreamHandler​(ExecuteStreamHandler streamHandler)
      Set a custom the StreamHandler used for providing input and retrieving the output.
      void setWatchdog​(ExecuteWatchdog watchDog)
      Set the watchdog used to kill of processes running, typically, too long time.
      void setWorkingDirectory​(java.io.File dir)
      Set the working directory of the created process.
      • Methods inherited from class java.lang.Object

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

      • workingDirectory

        private java.io.File workingDirectory
        the working directory of the process
      • watchdog

        private ExecuteWatchdog watchdog
        monitoring of long running processes
      • exitValues

        private int[] exitValues
        the exit values considered to be successful
      • launcher

        private final CommandLauncher launcher
        launches the command in a new process
      • processDestroyer

        private ProcessDestroyer processDestroyer
        optional cleanup of started processes
      • executorThread

        private java.lang.Thread executorThread
        worker thread for asynchronous execution
      • exceptionCaught

        private java.io.IOException exceptionCaught
        the first exception being caught to be thrown to the caller
    • Constructor Detail

      • DefaultExecutor

        public DefaultExecutor()
        Default constructor creating a default PumpStreamHandler and sets the working directory of the subprocess to the current working directory. The PumpStreamHandler pumps the output of the subprocess into our System.out and System.err to avoid into our System.out and System.err to avoid a blocked or deadlocked subprocess (seeProcess).
    • Method Detail

      • execute

        public int execute​(CommandLine command,
                           java.util.Map<java.lang.String,​java.lang.String> environment)
                    throws ExecuteException,
                           java.io.IOException
        Description copied from interface: Executor
        Methods for starting synchronous execution.
        Specified by:
        execute in interface Executor
        Parameters:
        command - the command to execute
        environment - The environment for the new process. If null, the environment of the current process is used.
        Returns:
        process exit value
        Throws:
        ExecuteException - execution of subprocess failed or the subprocess returned a exit value indicating a failure Executor.setExitValue(int).
        java.io.IOException
        See Also:
        Executor.execute(CommandLine, java.util.Map)
      • setExitValues

        public void setExitValues​(int[] values)
        Description copied from interface: Executor
        Define a list of exitValue of the process to be considered successful. The caller can pass one of the following values
        • an array of exit values to be considered successful
        • an empty array for auto-detect of successful exit codes relying on Executor.isFailure(int)
        • null to indicate to skip checking of exit codes
        If an undefined exit value is returned by the process then Executor.execute(CommandLine) will throw an ExecuteException.
        Specified by:
        setExitValues in interface Executor
        Parameters:
        values - a list of the exit codes
        See Also:
        Executor.setExitValues(int[])
      • isFailure

        public boolean isFailure​(int exitValue)
        Description copied from interface: Executor
        Checks whether exitValue signals a failure. If no exit values are set than the default conventions of the OS is used. e.g. most OS regard an exit code of '0' as successful execution and everything else as failure.
        Specified by:
        isFailure in interface Executor
        Parameters:
        exitValue - the exit value (return code) to be checked
        Returns:
        true if exitValue signals a failure
        See Also:
        Executor.isFailure(int)
      • createThread

        protected java.lang.Thread createThread​(java.lang.Runnable runnable,
                                                java.lang.String name)
        Factory method to create a thread waiting for the result of an asynchronous execution.
        Parameters:
        runnable - the runnable passed to the thread
        name - the name of the thread
        Returns:
        the thread
      • launch

        protected java.lang.Process launch​(CommandLine command,
                                           java.util.Map<java.lang.String,​java.lang.String> env,
                                           java.io.File dir)
                                    throws java.io.IOException
        Creates a process that runs a command.
        Parameters:
        command - the command to run
        env - the environment for the command
        dir - the working directory for the command
        Returns:
        the process started
        Throws:
        java.io.IOException - forwarded from the particular launcher used
      • getExecutorThread

        protected java.lang.Thread getExecutorThread()
        Get the worker thread being used for asynchronous execution.
        Returns:
        the worker thread
      • closeProcessStreams

        private void closeProcessStreams​(java.lang.Process process)
        Close the streams belonging to the given Process.
        Parameters:
        process - the Process.
      • executeInternal

        private int executeInternal​(CommandLine command,
                                    java.util.Map<java.lang.String,​java.lang.String> environment,
                                    java.io.File dir,
                                    ExecuteStreamHandler streams)
                             throws java.io.IOException
        Execute an internal process. If the executing thread is interrupted while waiting for the child process to return the child process will be killed.
        Parameters:
        command - the command to execute
        environment - the execution environment
        dir - the working directory
        streams - process the streams (in, out, err) of the process
        Returns:
        the exit code of the process
        Throws:
        java.io.IOException - executing the process failed
      • setExceptionCaught

        private void setExceptionCaught​(java.io.IOException e)
        Keep track of the first IOException being thrown.
        Parameters:
        e - the IOException
      • getExceptionCaught

        private java.io.IOException getExceptionCaught()
        Get the first IOException being thrown.
        Returns:
        the first IOException being caught