org.apache.commons.exec
Class DefaultExecutor

java.lang.Object
  extended by org.apache.commons.exec.DefaultExecutor
All Implemented Interfaces:
Executor

public class DefaultExecutor
extends java.lang.Object
implements Executor

The default class to start a subprocess. The implementation allows to

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, java.util.Map environment)
          Methods for starting synchronous execution.
 void execute(CommandLine command, java.util.Map environment, ExecuteResultHandler handler)
          Methods for starting asynchronous execution.
protected  java.lang.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.
 java.io.File getWorkingDirectory()
          Get the working directory of the created process.
 boolean isFailure(int exitValue)
          Checks whether exitValue signals a failure.
protected  java.lang.Process launch(CommandLine command, java.util.Map env, java.io.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(java.io.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 java.io.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(java.io.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,
                   java.io.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).
java.io.IOException
See Also:
Executor.execute(CommandLine)

execute

public int execute(CommandLine command,
                   java.util.Map environment)
            throws ExecuteException,
                   java.io.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).
java.io.IOException
See Also:
Executor.execute(CommandLine, java.util.Map)

execute

public void execute(CommandLine command,
                    ExecuteResultHandler handler)
             throws ExecuteException,
                    java.io.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
java.io.IOException
See Also:
Executor.execute(CommandLine, org.apache.commons.exec.ExecuteResultHandler)

execute

public void execute(CommandLine command,
                    java.util.Map environment,
                    ExecuteResultHandler handler)
             throws ExecuteException,
                    java.io.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
java.io.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 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 java.lang.Process launch(CommandLine command,
                                   java.util.Map env,
                                   java.io.File dir)
                            throws java.io.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:
java.io.IOException - forwarded from the particular launcher used

getExecutorThread

protected java.lang.Thread getExecutorThread()
Get the worker thread being used for asynchronous execution.

Returns:
the worker thread


Copyright © 2011 Apache Software Foundation. All Rights Reserved.