org.apache.tools.ant.taskdefs

Class Execute

public class Execute extends Object

Runs an external program.

Since: Ant 1.2

Field Summary
static intINVALID
Invalid exit code.
Constructor Summary
Execute()
Creates a new execute object using PumpStreamHandler for stream handling.
Execute(ExecuteStreamHandler streamHandler)
Creates a new execute object.
Execute(ExecuteStreamHandler streamHandler, ExecuteWatchdog watchdog)
Creates a new execute object.
Method Summary
static voidcloseStreams(Process process)
Close the streams belonging to the given Process.
intexecute()
Runs a process defined by the command line and returns its exit status.
String[]getCommandline()
Returns the commandline used to create a subprocess.
String[]getEnvironment()
Returns the environment used to create a subprocess.
intgetExitValue()
Query the exit value of the process.
static VectorgetProcEnvironment()
Find the list of environment variables for this process.
static booleanisFailure(int exitValue)
Checks whether exitValue signals a failure on the current system (OS specific).
booleankilledProcess()
test for an untimely death of the process
static Processlaunch(Project project, String[] command, String[] env, File dir, boolean useVM)
Creates a process that runs a command.
static voidrunCommand(Task task, String[] cmdline)
A utility method that runs an external command.
voidsetAntRun(Project project)
Set the name of the antRun script using the project's value.
voidsetCommandline(String[] commandline)
Sets the commandline of the subprocess to launch.
voidsetEnvironment(String[] env)
Sets the environment variables for the subprocess to launch.
protected voidsetExitValue(int value)
set the exit value
voidsetNewenvironment(boolean newenv)
Set whether to propagate the default environment or not.
voidsetSpawn(boolean spawn)
set whether or not you want the process to be spawned default is not spawned
voidsetStreamHandler(ExecuteStreamHandler streamHandler)
voidsetVMLauncher(boolean useVMLauncher)
Launch this execution through the VM, where possible, rather than through the OS's shell.
voidsetWorkingDirectory(File wd)
Sets the working directory of the process to execute.
voidspawn()
Starts a process defined by the command line.
static StringtoString(ByteArrayOutputStream bos)
ByteArrayOutputStream#toString doesn't seem to work reliably on OS/390, at least not the way we use it in the execution context.
protected voidwaitFor(Process process)
wait for a given process

Field Detail

INVALID

public static final int INVALID
Invalid exit code. *

Constructor Detail

Execute

public Execute()
Creates a new execute object using PumpStreamHandler for stream handling.

Execute

public Execute(ExecuteStreamHandler streamHandler)
Creates a new execute object.

Parameters: streamHandler the stream handler used to handle the input and output streams of the subprocess.

Execute

public Execute(ExecuteStreamHandler streamHandler, ExecuteWatchdog watchdog)
Creates a new execute object.

Parameters: streamHandler the stream handler used to handle the input and output streams of the subprocess. watchdog a watchdog for the subprocess or null to to disable a timeout for the subprocess.

Method Detail

closeStreams

public static void closeStreams(Process process)
Close the streams belonging to the given Process.

Parameters: process the Process.

execute

public int execute()
Runs a process defined by the command line and returns its exit status.

Returns: the exit status of the subprocess or INVALID

Throws: java.io.IOException The exception is thrown, if launching of the subprocess failed

getCommandline

public String[] getCommandline()
Returns the commandline used to create a subprocess.

Returns: the commandline used to create a subprocess

getEnvironment

public String[] getEnvironment()
Returns the environment used to create a subprocess.

Returns: the environment used to create a subprocess

getExitValue

public int getExitValue()
Query the exit value of the process.

Returns: the exit value or Execute.INVALID if no exit value has been received

getProcEnvironment

public static Vector getProcEnvironment()
Find the list of environment variables for this process.

Returns: a vector containing the environment variables the vector elements are strings formatted like variable = value

isFailure

public static boolean isFailure(int exitValue)
Checks whether exitValue signals a failure on the current system (OS specific).

Note that this method relies on the conventions of the OS, it will return false results if the application you are running doesn't follow these conventions. One notable exception is the Java VM provided by HP for OpenVMS - it will return 0 if successful (like on any other platform), but this signals a failure on OpenVMS. So if you execute a new Java VM on OpenVMS, you cannot trust this method.

Parameters: exitValue the exit value (return code) to be checked

Returns: true if exitValue signals a failure

killedProcess

public boolean killedProcess()
test for an untimely death of the process

Returns: true if a watchdog had to kill the process

Since: Ant 1.5

launch

public static Process launch(Project project, String[] command, String[] env, File dir, boolean useVM)
Creates a process that runs a command.

Parameters: project the Project, only used for logging purposes, may be null. command the command to run env the environment for the command dir the working directory for the command useVM use the built-in exec command for JDK 1.3 if available.

Returns: the process started

Throws: IOException forwarded from the particular launcher used

Since: Ant 1.5

runCommand

public static void runCommand(Task task, String[] cmdline)
A utility method that runs an external command. Writes the output and error streams of the command to the project log.

Parameters: task The task that the command is part of. Used for logging cmdline The command to execute.

Throws: BuildException if the command does not return 0.

setAntRun

public void setAntRun(Project project)
Set the name of the antRun script using the project's value.

Parameters: project the current project.

Throws: BuildException not clear when it is going to throw an exception, but it is the method's signature

setCommandline

public void setCommandline(String[] commandline)
Sets the commandline of the subprocess to launch.

Parameters: commandline the commandline of the subprocess to launch

setEnvironment

public void setEnvironment(String[] env)
Sets the environment variables for the subprocess to launch.

Parameters: env array of Strings, each element of which has an environment variable settings in format key=value

setExitValue

protected void setExitValue(int value)
set the exit value

Parameters: value exit value of the process

setNewenvironment

public void setNewenvironment(boolean newenv)
Set whether to propagate the default environment or not.

Parameters: newenv whether to propagate the process environment.

setSpawn

public void setSpawn(boolean spawn)
set whether or not you want the process to be spawned default is not spawned

Parameters: spawn if true you do not want ant to wait for the end of the process

Since: ant 1.6

setStreamHandler

public void setStreamHandler(ExecuteStreamHandler streamHandler)

Since: Ant 1.6

setVMLauncher

public void setVMLauncher(boolean useVMLauncher)
Launch this execution through the VM, where possible, rather than through the OS's shell. In some cases and operating systems using the shell will allow the shell to perform additional processing such as associating an executable with a script, etc

Parameters: useVMLauncher true if exec should launch through the VM, false if the shell should be used to launch the command.

setWorkingDirectory

public void setWorkingDirectory(File wd)
Sets the working directory of the process to execute.

This is emulated using the antRun scripts unless the OS is Windows NT in which case a cmd.exe is spawned, or MRJ and setting user.dir works, or JDK 1.3 and there is official support in java.lang.Runtime.

Parameters: wd the working directory of the process.

spawn

public void spawn()
Starts a process defined by the command line. Ant will not wait for this process, nor log its output

Throws: java.io.IOException The exception is thrown, if launching of the subprocess failed

Since: ant 1.6

toString

public static String toString(ByteArrayOutputStream bos)
ByteArrayOutputStream#toString doesn't seem to work reliably on OS/390, at least not the way we use it in the execution context.

Parameters: bos the output stream that one wants to read

Returns: the output stream as a string, read with special encodings in the case of z/os and os/400

Since: Ant 1.5

waitFor

protected void waitFor(Process process)
wait for a given process

Parameters: process the process one wants to wait for

Copyright B) 2000-2007 Apache Software Foundation. All Rights Reserved.