Package org.apache.commons.exec
Class DefaultExecutor
java.lang.Object
org.apache.commons.exec.DefaultExecutor
- All Implemented Interfaces:
Executor
- Direct Known Subclasses:
DaemonExecutor
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
Executor exec = new DefaultExecutor(); CommandLine cl = new CommandLine("ls -l"); int exitvalue = exec.execute(cl);
- Version:
- $Id: DefaultExecutor.java 1636056 2014-11-01 21:12:52Z ggregory $
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate IOException
the first exception being caught to be thrown to the callerprivate Thread
worker thread for asynchronous executionprivate int[]
the exit values considered to be successfulprivate final CommandLauncher
launches the command in a new processprivate ProcessDestroyer
optional cleanup of started processesprivate ExecuteStreamHandler
taking care of output and error streamprivate ExecuteWatchdog
monitoring of long running processesprivate File
the working directory of the processFields inherited from interface org.apache.commons.exec.Executor
INVALID_EXITVALUE
-
Constructor Summary
ConstructorsConstructorDescriptionDefault constructor creating a defaultPumpStreamHandler
and sets the working directory of the subprocess to the current working directory. -
Method Summary
Modifier and TypeMethodDescriptionprivate void
closeProcessStreams
(Process process) Close the streams belonging to the given Process.protected Thread
createThread
(Runnable runnable, 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.int
execute
(CommandLine command, Map<String, String> environment) Methods for starting synchronous execution.void
execute
(CommandLine command, Map<String, String> environment, ExecuteResultHandler handler) Methods for starting asynchronous execution.void
execute
(CommandLine command, ExecuteResultHandler handler) Methods for starting asynchronous execution.private int
executeInternal
(CommandLine command, Map<String, String> environment, File dir, ExecuteStreamHandler streams) Execute an internal process.private IOException
Get the first IOException being thrown.protected Thread
Get the worker thread being used for asynchronous execution.Set the handler for cleanup of started processes if the main process is going to terminate.Get the StreamHandler used for providing input and retrieving the output.Get the watchdog used to kill of processes running, typically, too long time.Get the working directory of the created process.boolean
isFailure
(int exitValue) Checks whetherexitValue
signals a failure.protected Process
Creates a process that runs a command.private void
Keep track of the first IOException being thrown.void
setExitValue
(int value) Define theexitValue
of the process to be considered successful.void
setExitValues
(int[] values) Define a list ofexitValue
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.
-
Field Details
-
streamHandler
taking care of output and error stream -
workingDirectory
the working directory of the process -
watchdog
monitoring of long running processes -
exitValues
private int[] exitValuesthe exit values considered to be successful -
launcher
launches the command in a new process -
processDestroyer
optional cleanup of started processes -
executorThread
worker thread for asynchronous execution -
exceptionCaught
the first exception being caught to be thrown to the caller
-
-
Constructor Details
-
DefaultExecutor
public DefaultExecutor()Default constructor creating a defaultPumpStreamHandler
and sets the working directory of the subprocess to the current working directory. ThePumpStreamHandler
pumps the output of the subprocess into ourSystem.out
andSystem.err
to avoid into ourSystem.out
andSystem.err
to avoid a blocked or deadlocked subprocess (seeProcess
).
-
-
Method Details
-
getStreamHandler
Description copied from interface:Executor
Get the StreamHandler used for providing input and retrieving the output.- Specified by:
getStreamHandler
in interfaceExecutor
- Returns:
- the StreamHandler
- See Also:
-
setStreamHandler
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 (seeProcess
).- Specified by:
setStreamHandler
in interfaceExecutor
- Parameters:
streamHandler
- the stream handler- See Also:
-
getWatchdog
Description copied from interface:Executor
Get the watchdog used to kill of processes running, typically, too long time.- Specified by:
getWatchdog
in interfaceExecutor
- Returns:
- the watchdog
- See Also:
-
setWatchdog
Description copied from interface:Executor
Set the watchdog used to kill of processes running, typically, too long time.- Specified by:
setWatchdog
in interfaceExecutor
- Parameters:
watchDog
- the watchdog- See Also:
-
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 interfaceExecutor
- Returns:
- the ProcessDestroyer
- See Also:
-
setProcessDestroyer
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 interfaceExecutor
- Parameters:
processDestroyer
- the ProcessDestroyer- See Also:
-
getWorkingDirectory
Description copied from interface:Executor
Get the working directory of the created process.- Specified by:
getWorkingDirectory
in interfaceExecutor
- Returns:
- the working directory
- See Also:
-
setWorkingDirectory
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 interfaceExecutor
- Parameters:
dir
- the working directory- See Also:
-
execute
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 interfaceExecutor
- 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 failureExecutor.setExitValue(int)
.IOException
- See Also:
-
execute
public int execute(CommandLine command, Map<String, String> environment) throws ExecuteException, IOExceptionDescription copied from interface:Executor
Methods for starting synchronous execution.- Specified by:
execute
in interfaceExecutor
- Parameters:
command
- the command to executeenvironment
- 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 failureExecutor.setExitValue(int)
.IOException
- See Also:
-
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 interfaceExecutor
- Parameters:
command
- the command to executehandler
- capture process termination and exit code- Throws:
ExecuteException
- execution of subprocess failedIOException
- See Also:
-
execute
public void execute(CommandLine command, Map<String, String> environment, ExecuteResultHandler handler) throws ExecuteException, IOExceptionDescription 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 interfaceExecutor
- Parameters:
command
- the command to executeenvironment
- 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 failedIOException
- See Also:
-
setExitValue
public void setExitValue(int value) Description copied from interface:Executor
Define theexitValue
of the process to be considered successful. If a different exit value is returned by the process thenExecutor.execute(CommandLine)
will throw anExecuteException
- Specified by:
setExitValue
in interfaceExecutor
- Parameters:
value
- the exit code representing successful execution- See Also:
-
setExitValues
public void setExitValues(int[] values) Description copied from interface:Executor
Define a list ofexitValue
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
Executor.execute(CommandLine)
will throw anExecuteException
.- Specified by:
setExitValues
in interfaceExecutor
- Parameters:
values
- a list of the exit codes- See Also:
-
isFailure
public boolean isFailure(int exitValue) Description copied from interface:Executor
Checks whetherexitValue
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. -
createThread
Factory method to create a thread waiting for the result of an asynchronous execution.- Parameters:
runnable
- the runnable passed to the threadname
- the name of the thread- Returns:
- the thread
-
launch
Creates a process that runs a command.- Parameters:
command
- the command to runenv
- the environment for the commanddir
- the working directory for the command- Returns:
- the process started
- Throws:
IOException
- forwarded from the particular launcher used
-
getExecutorThread
Get the worker thread being used for asynchronous execution.- Returns:
- the worker thread
-
closeProcessStreams
Close the streams belonging to the given Process.- Parameters:
process
- theProcess
.
-
executeInternal
private int executeInternal(CommandLine command, Map<String, String> environment, File dir, ExecuteStreamHandler streams) throws IOExceptionExecute an internal process. If the executing thread is interrupted while waiting for the child process to return the child process will be killed.- Parameters:
command
- the command to executeenvironment
- the execution environmentdir
- the working directorystreams
- process the streams (in, out, err) of the process- Returns:
- the exit code of the process
- Throws:
IOException
- executing the process failed
-
setExceptionCaught
Keep track of the first IOException being thrown.- Parameters:
e
- the IOException
-
getExceptionCaught
Get the first IOException being thrown.- Returns:
- the first IOException being caught
-