Package org.apache.commons.exec

Class DefaultExecutor

java.lang.Object

org.apache.commons.exec.DefaultExecutor

All Implemented Interfaces:

Executor

Direct Known Subclasses:

DaemonExecutor

public class DefaultExecutor
extends java.lang.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 inherited from interface org.apache.commons.exec.Executor

INVALID_EXITVALUE

Constructor Summary

Constructors

Constructor	Description
DefaultExecutor()	Deprecated. Use DefaultExecutor.Builder.get().

Method Summary

Modifier and Type	Method	Description
static DefaultExecutor.Builder<?>	builder()	Creates a new builder.
protected java.lang.Thread	createThread(java.lang.Runnable runnable, java.lang.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, java.util.Map<java.lang.String,java.lang.String> environment)	Executes a command synchronously.
void	execute(CommandLine command, java.util.Map<java.lang.String,java.lang.String> environment, ExecuteResultHandler handler)	Executes a command asynchronously.
void	execute(CommandLine command, ExecuteResultHandler handler)	Executes a command asynchronously.
protected java.lang.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.
ExecuteWatchdog	getWatchdog()	Gets the watchdog used to kill of processes running, typically, too long time.
java.io.File	getWorkingDirectory()	Gets the working directory of the created process.
boolean	isFailure(int exitValue)	Tests whether exitValue signals a failure.
protected java.lang.Process	launch(CommandLine command, java.util.Map<java.lang.String,java.lang.String> env, java.io.File workingDirectory)	Creates a process that runs a command.
protected java.lang.Process	launch(CommandLine command, java.util.Map<java.lang.String,java.lang.String> env, java.nio.file.Path workingDirectory)	Creates a process that runs a command.
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.
void	setWatchdog(ExecuteWatchdog watchdog)	Sets the watchdog used to kill of processes running, typically, too long time.
void	setWorkingDirectory(java.io.File workingDirectory)	Deprecated. Use DefaultExecutor.Builder.setWorkingDirectory(File).

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

Constructor Detail

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

Method Detail

builder

public static DefaultExecutor.Builder<?> builder()

Creates a new builder.

Returns:

a new builder.

Since:

1.4.0

createThread

protected java.lang.Thread createThread(java.lang.Runnable runnable,
                                        java.lang.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,
                   java.io.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).

java.io.IOException - If an I/O error occurs.

See Also:

Executor.execute(CommandLine)

execute

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

java.io.IOException - If an I/O error occurs.

See Also:

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

execute

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

java.io.IOException - If an I/O error occurs.

See Also:

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

execute

public void execute(CommandLine command,
                    java.util.Map<java.lang.String,java.lang.String> environment,
                    ExecuteResultHandler handler)
             throws ExecuteException,
                    java.io.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.

java.io.IOException - If an I/O error occurs.

See Also:

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

getExecutorThread

protected java.lang.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()

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 java.io.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 java.lang.Process launch(CommandLine command,
                                   java.util.Map<java.lang.String,java.lang.String> env,
                                   java.io.File workingDirectory)
                            throws java.io.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:

java.io.IOException - forwarded from the particular launcher used.

launch

protected java.lang.Process launch(CommandLine command,
                                   java.util.Map<java.lang.String,java.lang.String> env,
                                   java.nio.file.Path workingDirectory)
                            throws java.io.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:

java.io.IOException - forwarded from the particular launcher used.

Since:

1.5.0

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)

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(java.io.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)