Package 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 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 = DefaultExecutor.builder().get();
     CommandLine cl = new CommandLine("ls -l");
     int exitValue = exec.execute(cl);

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `DefaultExecutor.Builder<T extends DefaultExecutor.Builder<T>>`
  Constructs a new `DefaultExecutor`.

- ## Field Summary

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

  `INVALID_EXITVALUE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultExecutor()`
  Deprecated.
  Use `DefaultExecutor.Builder.get()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static DefaultExecutor.Builder<?>`
  `builder()`
  Creates a new builder.
  `protected Thread`
  `createThread(Runnable runnable, String name)`
  Creates a thread waiting for the result of an asynchronous execution.
  `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.
  `protected Thread`
  `getExecutorThread()`
  Gets the worker thread being used for asynchronous execution.
  `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.
  `protected Process`
  `launch(CommandLine command, Map<String,String> env, File workingDirectory)`
  Creates a process that runs a command.
  `protected Process`
  `launch(CommandLine command, Map<String,String> env, Path workingDirectory)`
  Creates a process that runs a command.
  `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 workingDirectory)`
  Deprecated.
  Use `DefaultExecutor.Builder.setWorkingDirectory(File)`.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface org.apache.commons.exec.Executor

  `getWorkingDirectoryPath`

- ## Constructor Details

  - ### DefaultExecutor

    @Deprecated public DefaultExecutor()
    Deprecated.
    Use `DefaultExecutor.Builder.get()`.
    Constructs 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 Details

  - ### builder

    public static DefaultExecutor.Builder<?> builder()
    Creates a new builder.
    Returns:
      a new builder.
    Since:
      1.4.0

  - ### createThread

    protected Thread createThread(Runnable runnable, String name)
    Creates 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

  - ### execute

    public int execute(CommandLine command) throws ExecuteException, IOException
    Description copied from interface: `Executor`
    Executes a command synchronously. 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 an exit value indicating a failure `Executor.setExitValue(int)`.
      `IOException` - If an I/O error occurs.
    See Also:
      - `Executor.execute(CommandLine)`

  - ### execute

    public void execute(CommandLine command, ExecuteResultHandler handler) throws ExecuteException, IOException
    Description copied from interface: `Executor`
    Executes a command asynchronously. 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.
      `IOException` - If an I/O error occurs.
    See Also:
      - `Executor.execute(CommandLine, org.apache.commons.exec.ExecuteResultHandler)`

  - ### execute

    public int execute(CommandLine command, Map<String,String> environment) throws ExecuteException, IOException
    Description copied from interface: `Executor`
    Executes a command synchronously.
    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 an exit value indicating a failure `Executor.setExitValue(int)`.
      `IOException` - If an I/O error occurs.
    See Also:
      - `Executor.execute(CommandLine, java.util.Map)`

  - ### execute

    public void execute(CommandLine command, Map<String,String> environment, ExecuteResultHandler handler) throws ExecuteException, IOException
    Description copied from interface: `Executor`
    Executes a command asynchronously. 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.
      `IOException` - If an I/O error occurs.
    See Also:
      - `Executor.execute(CommandLine, java.util.Map, org.apache.commons.exec.ExecuteResultHandler)`

  - ### getExecutorThread

    protected Thread getExecutorThread()
    Gets the worker thread being used for asynchronous execution.
    Returns:
      the worker thread.

  - ### getProcessDestroyer

    public ProcessDestroyer getProcessDestroyer()
    Description copied from interface: `Executor`
    Sets 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()`

  - ### getStreamHandler

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

  - ### getWatchdog

    public ExecuteWatchdog getWatchdog()
    Description copied from interface: `Executor`
    Gets 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()`

  - ### getWorkingDirectory

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

  - ### isFailure

    public boolean isFailure(int exitValue)
    Description copied from interface: `Executor`
    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.
    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)`

  - ### launch

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

  - ### launch

    protected Process launch(CommandLine command, Map<String,String> env, Path workingDirectory) throws IOException
    Creates a process that runs a command.
    Parameters:
      `command` - the command to run.
      `env` - the environment for the command.
      `workingDirectory` - the working directory for the command.
    Returns:
      the process started.
    Throws:
      `IOException` - forwarded from the particular launcher used.
    Since:
      1.5.0

  - ### setExitValue

    public 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 `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`
    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 `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[])`

  - ### setProcessDestroyer

    public void setProcessDestroyer(ProcessDestroyer processDestroyer)
    Description copied from interface: `Executor`
    Sets 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)`

  - ### setStreamHandler

    public void setStreamHandler(ExecuteStreamHandler streamHandler)
    Description copied from interface: `Executor`
    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`).
    Specified by:
      `setStreamHandler` in interface `Executor`
    Parameters:
      `streamHandler` - the stream handler.
    See Also:
      - `Executor.setStreamHandler(org.apache.commons.exec.ExecuteStreamHandler)`

  - ### setWatchdog

    public void setWatchdog(ExecuteWatchdog watchdog)
    Description copied from interface: `Executor`
    Sets 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)`

  - ### setWorkingDirectory

    @Deprecated public void setWorkingDirectory(File workingDirectory)
    Deprecated.
    Use `DefaultExecutor.Builder.setWorkingDirectory(File)`.
    Sets the working directory.
    Specified by:
      `setWorkingDirectory` in interface `Executor`
    Parameters:
      `workingDirectory` - the working directory.
    See Also:
      - `Executor.setWorkingDirectory(java.io.File)`