org.apache.commons.exec
Class DefaultExecutor

java.lang.Object
  org.apache.commons.exec.DefaultExecutor

All Implemented Interfaces:

Executor

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

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

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.
protected 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.
File	getWorkingDirectory() Get the working directory of the created process.
boolean	isFailure(int exitValue) Checks whether exitValue signals a failure.
protected Process	launch(CommandLine command, Map env, 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(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 (seeProcess).

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 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(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,
                   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).

IOException

See Also:

Executor.execute(CommandLine)

execute

public int execute(CommandLine command,
                   Map environment)
            throws ExecuteException,
                   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).

IOException

See Also:

Executor.execute(CommandLine, java.util.Map)

execute

public void execute(CommandLine command,
                    ExecuteResultHandler handler)
             throws ExecuteException,
                    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

IOException

See Also:

Executor.execute(CommandLine, org.apache.commons.exec.ExecuteResultHandler)

execute

public void execute(CommandLine command,
                    Map environment,
                    ExecuteResultHandler handler)
             throws ExecuteException,
                    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

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)

launch

protected Process launch(CommandLine command,
                         Map env,
                         File dir)
                  throws 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:

IOException - forwarded from the particular launcher used

getExecutorThread

protected Thread getExecutorThread()

Get the worker thread being used for asynchronous execution.

Returns:

the worker thread