DefaultExecutor
Date: 2017-01-22

org.apache.commons.exec

## Class DefaultExecutor

- java.lang.Object
- - org.apache.commons.exec.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);

- - ### Field Summary

    - ### Fields inherited from interface org.apache.commons.exec.Executor

      `INVALID_EXITVALUE`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `void` | `execute(CommandLine command, ExecuteResultHandler handler)` Methods for starting asynchronous 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.
    `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.
    `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`

- - ### 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 (see`Process`).

  - ### Method Detail

    - #### getStreamHandler

          public ExecuteStreamHandler getStreamHandler()

      Description copied from interface: `Executor`
      Get the StreamHandler used for providing input and retrieving the output.
      Specified by:
        `getStreamHandler` in interface `Executor`
      Returns:
        the StreamHandler
      See Also:
        `Executor.getStreamHandler()`

    - #### setStreamHandler

          public void setStreamHandler(ExecuteStreamHandler streamHandler)

      Description copied from interface: `Executor`
      Set a custom the StreamHandler used for providing input and retrieving the output. If you don't provide a proper stream handler the executed process might block when writing to stdout and/or stderr (see `Process`).
      Specified by:
        `setStreamHandler` in interface `Executor`
      Parameters:
        `streamHandler` - the stream handler
      See Also:
        `Executor.setStreamHandler(org.apache.commons.exec.ExecuteStreamHandler)`

    - #### getWatchdog

          public ExecuteWatchdog getWatchdog()

      Description copied from interface: `Executor`
      Get the watchdog used to kill of processes running, typically, too long time.
      Specified by:
        `getWatchdog` in interface `Executor`
      Returns:
        the watchdog
      See Also:
        `Executor.getWatchdog()`

    - #### setWatchdog

          public void setWatchdog(ExecuteWatchdog watchDog)

      Description copied from interface: `Executor`
      Set the watchdog used to kill of processes running, typically, too long time.
      Specified by:
        `setWatchdog` in interface `Executor`
      Parameters:
        `watchDog` - the watchdog
      See Also:
        `Executor.setWatchdog(org.apache.commons.exec.ExecuteWatchdog)`

    - #### getProcessDestroyer

          public ProcessDestroyer getProcessDestroyer()

      Description copied from interface: `Executor`
      Set the handler for cleanup of started processes if the main process is going to terminate.
      Specified by:
        `getProcessDestroyer` in interface `Executor`
      Returns:
        the ProcessDestroyer
      See Also:
        `Executor.getProcessDestroyer()`

    - #### setProcessDestroyer

          public void setProcessDestroyer(ProcessDestroyer processDestroyer)

      Description copied from interface: `Executor`
      Get the handler for cleanup of started processes if the main process is going to terminate.
      Specified by:
        `setProcessDestroyer` in interface `Executor`
      Parameters:
        `processDestroyer` - the ProcessDestroyer
      See Also:
        `Executor.setProcessDestroyer(ProcessDestroyer)`

    - #### getWorkingDirectory

          public java.io.File getWorkingDirectory()

      Description copied from interface: `Executor`
      Get the working directory of the created process.
      Specified by:
        `getWorkingDirectory` in interface `Executor`
      Returns:
        the working directory
      See Also:
        `Executor.getWorkingDirectory()`

    - #### setWorkingDirectory

          public void setWorkingDirectory(java.io.File dir)

      Description copied from interface: `Executor`
      Set the working directory of the created process. The working directory must exist when you start the process.
      Specified by:
        `setWorkingDirectory` in interface `Executor`
      Parameters:
        `dir` - the working directory
      See Also:
        `Executor.setWorkingDirectory(java.io.File)`

    - #### execute

          public int execute(CommandLine command)
                      throws ExecuteException,
                             java.io.IOException

      Description copied from interface: `Executor`
      Methods for starting synchronous execution. The child process inherits all environment variables of the parent process.
      Specified by:
        `execute` in interface `Executor`
      Parameters:
        `command` - the command to execute
      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)`

    - #### 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)`

    - #### execute

          public void execute(CommandLine command,
                     ExecuteResultHandler handler)
                       throws ExecuteException,
                              java.io.IOException

      Description copied from interface: `Executor`
      Methods for starting asynchronous execution. The child process inherits all environment variables of the parent process. Result provided to callback handler.
      Specified by:
        `execute` in interface `Executor`
      Parameters:
        `command` - the command to execute
        `handler` - capture process termination and exit code
      Throws:
        `ExecuteException` - execution of subprocess failed
        `java.io.IOException`
      See Also:
        `Executor.execute(CommandLine, org.apache.commons.exec.ExecuteResultHandler)`

    - #### execute

          public void execute(CommandLine command,
                     java.util.Map<java.lang.String,java.lang.String> environment,
                     ExecuteResultHandler handler)
                       throws ExecuteException,
                              java.io.IOException

      Description copied from interface: `Executor`
      Methods for starting asynchronous execution. The child process inherits all environment variables of the parent process. Result provided to callback handler.
      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.
        `handler` - capture process termination and exit code
      Throws:
        `ExecuteException` - execution of subprocess failed
        `java.io.IOException`
      See Also:
        `Executor.execute(CommandLine, java.util.Map, org.apache.commons.exec.ExecuteResultHandler)`

    - #### setExitValue

          public void setExitValue(int value)

      Description copied from interface: `Executor`
      Define the `exitValue` of the process to be considered successful. If a different exit value is returned by the process then `Executor.execute(CommandLine)` will throw an `ExecuteException`
      Specified by:
        `setExitValue` in interface `Executor`
      Parameters:
        `value` - the exit code representing successful execution
      See Also:
        `Executor.setExitValue(int)`

    - #### 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