Package org.apache.commons.exec

# Interface Executor

All Known Implementing Classes:
  `DaemonExecutor`, `DefaultExecutor`

public interface Executor
The main abstraction to start an external process. The interface 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 = DefaultExecutor.builder().get();
     CommandLine cl = new CommandLine("ls -l");
     int exitvalue = exec.execute(cl);

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `INVALID_EXITVALUE`
  Invalid exit code.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `execute(CommandLine command)`
  Executes a command synchronously.
  `int`
  `execute(CommandLine command, Map<String,String> environment)`
  Executes a command synchronously.
  `void`
  `execute(CommandLine command, Map<String,String> environment, ExecuteResultHandler handler)`
  Executes a command asynchronously.
  `void`
  `execute(CommandLine command, ExecuteResultHandler handler)`
  Executes a command asynchronously.
  `ProcessDestroyer`
  `getProcessDestroyer()`
  Sets the handler for cleanup of started processes if the main process is going to terminate.
  `ExecuteStreamHandler`
  `getStreamHandler()`
  Gets the StreamHandler used for providing input and retrieving the output.
  `ExecuteWatchdog`
  `getWatchdog()`
  Gets the watchdog used to kill of processes running, typically, too long time.
  `File`
  `getWorkingDirectory()`
  Gets the working directory of the created process.
  `boolean`
  `isFailure(int exitValue)`
  Tests whether `exitValue` signals a failure.
  `void`
  `setExitValue(int value)`
  Sets the `exitValue` of the process to be considered successful.
  `void`
  `setExitValues(int[] values)`
  Sets a list of `exitValue` of the process to be considered successful.
  `void`
  `setProcessDestroyer(ProcessDestroyer processDestroyer)`
  Sets the handler for cleanup of started processes if the main process is going to terminate.
  `void`
  `setStreamHandler(ExecuteStreamHandler streamHandler)`
  Sets a custom the StreamHandler used for providing input and retrieving the output.
  `void`
  `setWatchdog(ExecuteWatchdog watchDog)`
  Sets the watchdog used to kill of processes running, typically, too long time.
  `void`
  `setWorkingDirectory(File dir)`
  Sets the working directory of the created process.

- ## Field Details

  - ### INVALID_EXITVALUE

    static final int INVALID_EXITVALUE
    Invalid exit code.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### execute

    int execute(CommandLine command) throws ExecuteException, IOException
    Executes a command synchronously. The child process inherits all environment variables of the parent process.
    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 `setExitValue(int)`.
      `IOException` - If an I/O error occurs.

  - ### execute

    void execute(CommandLine command, ExecuteResultHandler handler) throws ExecuteException, IOException
    Executes a command asynchronously. The child process inherits all environment variables of the parent process. Result provided to callback handler.
    Parameters:
      `command` - the command to execute.
      `handler` - capture process termination and exit code.
    Throws:
      `ExecuteException` - execution of subprocess failed.
      `IOException` - If an I/O error occurs.

  - ### execute

    int execute(CommandLine command, Map<String,String> environment) throws ExecuteException, IOException
    Executes a command synchronously.
    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 `setExitValue(int)`.
      `IOException` - If an I/O error occurs.

  - ### execute

    void execute(CommandLine command, Map<String,String> environment, ExecuteResultHandler handler) throws ExecuteException, IOException
    Executes a command asynchronously. The child process inherits all environment variables of the parent process. Result provided to callback handler.
    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.
      `IOException` - If an I/O error occurs.

  - ### getProcessDestroyer

    ProcessDestroyer getProcessDestroyer()
    Sets the handler for cleanup of started processes if the main process is going to terminate.
    Returns:
      the ProcessDestroyer.

  - ### getStreamHandler

    ExecuteStreamHandler getStreamHandler()
    Gets the StreamHandler used for providing input and retrieving the output.
    Returns:
      the StreamHandler.

  - ### getWatchdog

    ExecuteWatchdog getWatchdog()
    Gets the watchdog used to kill of processes running, typically, too long time.
    Returns:
      the watchdog.

  - ### getWorkingDirectory

    File getWorkingDirectory()
    Gets the working directory of the created process.
    Returns:
      the working directory.

  - ### isFailure

    boolean isFailure(int exitValue)
    Tests 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.
    Parameters:
      `exitValue` - the exit value (return code) to be checked.
    Returns:
      `true` if `exitValue` signals a failure.

  - ### setExitValue

    void setExitValue(int value)
    Sets the `exitValue` of the process to be considered successful. If a different exit value is returned by the process then `execute(CommandLine)` will throw an `ExecuteException`.
    Parameters:
      `value` - the exit code representing successful execution.

  - ### setExitValues

    void setExitValues(int[] values)
    Sets 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 `isFailure(int)`
    - null to indicate to skip checking of exit codes
    If an undefined exit value is returned by the process then `execute(CommandLine)` will throw an `ExecuteException`.
    Parameters:
      `values` - a list of the exit codes.

  - ### setProcessDestroyer

    void setProcessDestroyer(ProcessDestroyer processDestroyer)
    Sets the handler for cleanup of started processes if the main process is going to terminate.
    Parameters:
      `processDestroyer` - the ProcessDestroyer.

  - ### setStreamHandler

    void setStreamHandler(ExecuteStreamHandler streamHandler)
    Sets 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`).
    Parameters:
      `streamHandler` - the stream handler.

  - ### setWatchdog

    void setWatchdog(ExecuteWatchdog watchDog)
    Sets the watchdog used to kill of processes running, typically, too long time.
    Parameters:
      `watchDog` - the watchdog.

  - ### setWorkingDirectory

    void setWorkingDirectory(File dir)
    Sets the working directory of the created process. The working directory must exist when you start the process.
    Parameters:
      `dir` - the working directory.