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 = DefaultExecutor.builder().get(); CommandLine cl = new CommandLine("ls -l"); int exitvalue = exec.execute(cl);
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
DefaultExecutor.Builder<T extends DefaultExecutor.Builder<T>>
Constructs a newDefaultExecutor
. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate IOException
The first exception being caught to be thrown to the caller.private ExecuteStreamHandler
Taking care of output and error stream.private Thread
Worker thread for asynchronous execution.private int[]
The exit values considered to be successful.private final CommandLauncher
Launches the command in a new process.private ProcessDestroyer
Optional cleanup of started processes.private final ThreadFactory
The thread factory.private ExecuteWatchdog
Monitoring of long running processes.private Path
The working directory of the process.Fields inherited from interface org.apache.commons.exec.Executor
INVALID_EXITVALUE
-
Constructor Summary
ConstructorsConstructorDescriptionDeprecated.DefaultExecutor
(ThreadFactory threadFactory, ExecuteStreamHandler executeStreamHandler, Path workingDirectory) -
Method Summary
Modifier and TypeMethodDescriptionstatic DefaultExecutor.Builder
<?> builder()
Creates a new builder.private void
private void
checkWorkingDirectory
(File directory) private void
checkWorkingDirectory
(Path directory) private void
closeCatch
(Closeable closeable) Closes the Closeable, remembering any exception.private void
closeProcessStreams
(Process process) Closes the streams belonging to the given Process.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.private int
executeInternal
(CommandLine command, Map<String, String> environment, Path workingDirectory, ExecuteStreamHandler streams) Execute an internal process.private IOException
Gets the first IOException being thrown.protected Thread
Gets the worker thread being used for asynchronous execution.Sets the handler for cleanup of started processes if the main process is going to terminate.Gets the StreamHandler used for providing input and retrieving the output.(package private) ThreadFactory
Gets the thread factory.Gets the watchdog used to kill of processes running, typically, too long time.Gets the working directory of the created process.boolean
isFailure
(int exitValue) Tests whetherexitValue
signals a failure.protected Process
Creates a process that runs a command.protected Process
Creates a process that runs a command.private void
Sets the first IOException thrown.void
setExitValue
(int value) Sets theexitValue
of the process to be considered successful.void
setExitValues
(int[] values) Sets a list ofexitValue
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.private void
setStreams
(ExecuteStreamHandler streams, Process process) void
setWatchdog
(ExecuteWatchdog watchdog) Sets the watchdog used to kill of processes running, typically, too long time.void
setWorkingDirectory
(File workingDirectory) Deprecated.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
-
Field Details
-
executeStreamHandler
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. -
threadFactory
The thread factory.
-
-
Constructor Details
-
DefaultExecutor
Deprecated.Constructs 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
). -
DefaultExecutor
DefaultExecutor(ThreadFactory threadFactory, ExecuteStreamHandler executeStreamHandler, Path workingDirectory)
-
-
Method Details
-
builder
Creates a new builder.- Returns:
- a new builder.
- Since:
- 1.4.0
-
checkWorkingDirectory
- Throws:
IOException
-
checkWorkingDirectory
- Throws:
IOException
-
checkWorkingDirectory
- Throws:
IOException
-
closeCatch
Closes the Closeable, remembering any exception.- Parameters:
closeable
- theCloseable
to close.
-
closeProcessStreams
Closes the streams belonging to the given Process.- Parameters:
process
- theProcess
.
-
createThread
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
Description copied from interface:Executor
Executes a command synchronously. 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
- If an I/O error occurs.- See Also:
-
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 interfaceExecutor
- 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:
-
execute
public int execute(CommandLine command, Map<String, String> environment) throws ExecuteException, IOExceptionDescription copied from interface:Executor
Executes a command synchronously.- Specified by:
execute
in interfaceExecutor
- 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 failureExecutor.setExitValue(int)
.IOException
- If an I/O error occurs.- See Also:
-
execute
public void execute(CommandLine command, Map<String, String> environment, ExecuteResultHandler handler) throws ExecuteException, IOExceptionDescription 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 interfaceExecutor
- 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:
-
executeInternal
private int executeInternal(CommandLine command, Map<String, String> environment, Path workingDirectory, 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 execute.environment
- the execution environment.workingDirectory
- the working directory.streams
- process the streams (in, out, err) of the process.- Returns:
- the exit code of the process.
- Throws:
IOException
- executing the process failed.
-
getExceptionCaught
Gets the first IOException being thrown.- Returns:
- the first IOException being caught.
-
getExecutorThread
Gets the worker thread being used for asynchronous execution.- Returns:
- the worker thread.
-
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 interfaceExecutor
- Returns:
- the ProcessDestroyer.
- See Also:
-
getStreamHandler
Description copied from interface:Executor
Gets the StreamHandler used for providing input and retrieving the output.- Specified by:
getStreamHandler
in interfaceExecutor
- Returns:
- the StreamHandler.
- See Also:
-
getThreadFactory
ThreadFactory getThreadFactory()Gets the thread factory. Z- Returns:
- the thread factory.
-
getWatchdog
Description copied from interface:Executor
Gets the watchdog used to kill of processes running, typically, too long time.- Specified by:
getWatchdog
in interfaceExecutor
- Returns:
- the watchdog.
- See Also:
-
getWorkingDirectory
Description copied from interface:Executor
Gets the working directory of the created process.- Specified by:
getWorkingDirectory
in interfaceExecutor
- Returns:
- the working directory.
- See Also:
-
isFailure
public boolean isFailure(int exitValue) Description copied from interface:Executor
Tests 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. -
launch
protected Process launch(CommandLine command, Map<String, String> env, File workingDirectory) throws IOExceptionCreates 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 IOExceptionCreates 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
-
setExceptionCaught
Sets the first IOException thrown.- Parameters:
e
- the IOException.
-
setExitValue
public void setExitValue(int value) Description copied from interface:Executor
Sets 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
Sets 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:
-
setProcessDestroyer
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 interfaceExecutor
- Parameters:
processDestroyer
- the ProcessDestroyer.- See Also:
-
setStreamHandler
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 (seeProcess
).- Specified by:
setStreamHandler
in interfaceExecutor
- Parameters:
streamHandler
- the stream handler.- See Also:
-
setStreams
- Throws:
IOException
-
setWatchdog
Description copied from interface:Executor
Sets the watchdog used to kill of processes running, typically, too long time.- Specified by:
setWatchdog
in interfaceExecutor
- Parameters:
watchdog
- the watchdog.- See Also:
-
setWorkingDirectory
Deprecated.Sets the working directory.- Specified by:
setWorkingDirectory
in interfaceExecutor
- Parameters:
workingDirectory
- the working directory.- See Also:
-
DefaultExecutor.Builder.get()
.