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

Modifier and Type	Field	Description
private IOException	exceptionCaught	The first exception being caught to be thrown to the caller.
private ExecuteStreamHandler	executeStreamHandler	Taking care of output and error stream.
private Thread	executorThread	Worker thread for asynchronous execution.
private int[]	exitValues	The exit values considered to be successful.
private final CommandLauncher	launcher	Launches the command in a new process.
private ProcessDestroyer	processDestroyer	Optional cleanup of started processes.
private final ThreadFactory	threadFactory	The thread factory.
private ExecuteWatchdog	watchdog	Monitoring of long-running processes.
private Path	workingDirectory	The working directory of the process.

Fields inherited from interface Executor

INVALID_EXITVALUE

Constructor Summary

Constructors

Constructor	Description
DefaultExecutor()	Deprecated. Use DefaultExecutor.Builder.get().
DefaultExecutor(DefaultExecutor.Builder<?> builder)

Method Summary

Modifier and Type	Method	Description
static DefaultExecutor.Builder<?>	builder()	Creates a new builder.
private void	checkWorkingDirectory()
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	getExceptionCaught()	Gets the first IOException being thrown.
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.
(package private) ThreadFactory	getThreadFactory()	Gets the thread factory.
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.
private void	setExceptionCaught(IOException e)	Sets the first IOException thrown.
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.
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. Use DefaultExecutor.Builder.setWorkingDirectory(File).

Methods inherited from class Object

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

Methods inherited from interface Executor

getWorkingDirectoryPath

Field Details

exceptionCaught

private IOException exceptionCaught

The first exception being caught to be thrown to the caller.

executeStreamHandler

private ExecuteStreamHandler executeStreamHandler

Taking care of output and error stream.

executorThread

private Thread executorThread

Worker thread for asynchronous execution.

exitValues

private int[] exitValues

The exit values considered to be successful.

launcher

private final CommandLauncher launcher

Launches the command in a new process.

processDestroyer

private ProcessDestroyer processDestroyer

Optional cleanup of started processes.

threadFactory

private final ThreadFactory threadFactory

The thread factory.

watchdog

private ExecuteWatchdog watchdog

Monitoring of long-running processes.

workingDirectory

private Path workingDirectory

The working directory of the process.

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

DefaultExecutor

DefaultExecutor(DefaultExecutor.Builder<?> builder)

Method Details

builder

public static DefaultExecutor.Builder<?> builder()

Creates a new builder.

Returns:

a new builder.

Since:

1.4.0

checkWorkingDirectory

private void checkWorkingDirectory()
                            throws IOException

Throws:

IOException

checkWorkingDirectory

private void checkWorkingDirectory(File directory)
                            throws IOException

Throws:

IOException

checkWorkingDirectory

private void checkWorkingDirectory(Path directory)
                            throws IOException

Throws:

IOException

closeCatch

private void closeCatch(Closeable closeable)

Closes the Closeable, remembering any exception.

Parameters:

closeable - the Closeable to close.

closeProcessStreams

private void closeProcessStreams(Process process)

Closes the streams belonging to the given Process.

Parameters:

process - the Process.

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)

executeInternal

private int executeInternal(CommandLine command,
 Map<String,String> environment,
 Path workingDirectory,
 ExecuteStreamHandler streams)
                     throws IOException

Execute 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

private IOException getExceptionCaught()

Gets the first IOException being thrown.

Returns:

the first IOException being caught.

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

getThreadFactory

ThreadFactory getThreadFactory()

Gets the thread factory. Z

Returns:

the thread factory.

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

setExceptionCaught

private void setExceptionCaught(IOException e)

Sets the first IOException thrown.

Parameters:

e - the IOException.

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)

setStreams

private void setStreams(ExecuteStreamHandler streams,
 Process process)
                 throws IOException

Throws:

IOException

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)