Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.exec
Interface Executor

All Known Implementing Classes:
  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 = new DefaultExecutor();
     CommandLine cl = new CommandLine("ls -l");
     int exitvalue = exec.execute(cl);

Field Summary
`static int` | `INVALID_EXITVALUE` Invalid exit code.

Method Summary
`int` | `execute(CommandLine command)` Methods for starting synchronous execution.
`void` | `execute(CommandLine command, ExecuteResultHandler handler)` Methods for starting asynchronous execution.
`int` | `execute(CommandLine command, Map environment)` Methods for starting synchronous execution.
`void` | `execute(CommandLine command, Map environment, ExecuteResultHandler handler)` Methods for starting 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 retriving the output.
`ExecuteWatchdog` | `getWatchdog()` Get the watchdog used to kill of processes running, typically, too long time.
`File` | `getWorkingDirectory()` Get the working directory of the created process.
`boolean` | `isFailure(int exitValue)` Checks whether `exitValue` signals a failure.
`void` | `setExitValue(int value)` Define the exit code of the process to considered successful.
`void` | `setExitValues(int[] values)` Define the exit code of the process to 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 the StreamHandler used for providing input and retriving the output.
`void` | `setWatchdog(ExecuteWatchdog watchDog)` Set the watchdog used to kill of processes running, typically, too long time.
`void` | `setWorkingDirectory(File dir)` Set the working directory of the created process.

Field Detail

### INVALID_EXITVALUE

    static final int INVALID_EXITVALUE

  Invalid exit code.

  See Also:
    Constant Field Values

Method Detail

### setExitValue

    void setExitValue(int value)

  Define the exit code of the process to considered successful.

  Parameters:
    `value` - the exit code representing successful execution

### setExitValues

    void setExitValues(int[] values)

  Define the exit code of the process to 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
  - null to indicate to skip checking of exit codes

  Parameters:
    `values` - a list of the exit codes

### isFailure

    boolean isFailure(int exitValue)

  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.

  Parameters:
    `exitValue` - the exit value (return code) to be checked
  Returns:
    `true` if `exitValue` signals a failure

### getStreamHandler

    ExecuteStreamHandler getStreamHandler()

  Get the StreamHandler used for providing input and retriving the output.

  Returns:
    the StreamHandler

### setStreamHandler

    void setStreamHandler(ExecuteStreamHandler streamHandler)

  Set the StreamHandler used for providing input and retriving the output.

  Parameters:
    `streamHandler` - the StreamHandler

### getWatchdog

    ExecuteWatchdog getWatchdog()

  Get the watchdog used to kill of processes running, typically, too long time.

  Returns:
    the watchdog

### setWatchdog

    void setWatchdog(ExecuteWatchdog watchDog)

  Set the watchdog used to kill of processes running, typically, too long time.

  Parameters:
    `watchDog` - the watchdog

### getProcessDestroyer

    ProcessDestroyer getProcessDestroyer()

  Set the handler for cleanup of started processes if the main process is going to terminate.

  Returns:
    the ProcessDestroyer

### setProcessDestroyer

    void setProcessDestroyer(ProcessDestroyer processDestroyer)

  Get the handler for cleanup of started processes if the main process is going to terminate.

  Parameters:
    `processDestroyer` - the ProcessDestroyer

### getWorkingDirectory

    File getWorkingDirectory()

  Get the working directory of the created process.

  Returns:
    the working directory

### setWorkingDirectory

    void setWorkingDirectory(File dir)

  Set the working directory of the created process. The working directory must exist when you start the process.

  Parameters:
    `dir` - the working directory

### execute

    int execute(CommandLine command)
                throws ExecuteException,
                       IOException

  Methods for starting synchronous execution. 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
    `IOException`

### execute

    int execute(CommandLine command,
                Map environment)
                throws ExecuteException,
                       IOException

  Methods for starting synchronous execution.

  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
    `IOException`

### execute

    void execute(CommandLine command,
                 ExecuteResultHandler handler)
                 throws ExecuteException,
                        IOException

  Methods for starting asynchronous execution. 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`

### execute

    void execute(CommandLine command,
                 Map environment,
                 ExecuteResultHandler handler)
                 throws ExecuteException,
                        IOException

  Methods for starting asynchronous execution. 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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2009 The Apache Software Foundation. All Rights Reserved.