Apache Ant 1.10.14 · org.apache.tools.ant.taskdefs.Execute

Modifier and Type	Field and Description
private static String	antWorkingDirectory
private String[]	cmdl
private String[]	env
private static boolean	environmentCaseInSensitive Used for replacing env variables
private int	exitValue
public static final int	INVALID Invalid exit code.
private boolean	newEnvironment
private static final int	ONE_SECOND
private static Map<String, String>	procEnvironment
private static ProcessDestroyer	processDestroyer Used to destroy processes when the VM exits.
private Project	project
private ExecuteStreamHandler	streamHandler
private boolean	useVMLauncher Controls whether the VM is used to launch commands, where possible.
private final ExecuteWatchdog	watchdog
private File	workingDirectory

Access	Constructor and Description
public	Execute() Creates a new execute object using `PumpStreamHandler` for stream handling.
public	Execute(ExecuteStreamHandler the stream handler used to handle the input and output streams of the subprocess. streamHandler) Creates a new execute object.
public	Execute(ExecuteStreamHandler the stream handler used to handle the input and output streams of the subprocess. streamHandler, ExecuteWatchdog a watchdog for the subprocess or `null` to disable a timeout for the subprocess. watchdog) Creates a new execute object.

Method Summary

Modifier and Type	Method and Description
public static void	closeStreams(Process the `Process`. process) Close the streams belonging to the given Process.
public int	Returns: the exit status of the subprocess or `INVALID`. execute() Runs a process defined by the command line and returns its exit status.
public String[]	Returns: the commandline used to create a subprocess. getCommandline() Returns the commandline used to create a subprocess.
public String[]	Returns: the environment used to create a subprocess. getEnvironment() Returns the environment used to create a subprocess.
public static synchronized Map<String, String>	Returns: a map containing the environment variables. getEnvironmentVariables() Find the list of environment variables for this process.
public int	Returns: the exit value or Execute.INVALID if no exit value has been received. getExitValue() Query the exit value of the process.
private static String[]	Returns: command and arguments to get our environment getProcEnvCommand() This is the operation to get our environment.
public static synchronized Vector<String>	Returns: a vector containing the environment variables. The vector elements are strings formatted like variable = value. getProcEnvironment() Deprecated use #getEnvironmentVariables instead Find the list of environment variables for this process.
private static Map<String, String>	getVMSLogicals(BufferedReader in) This method is VMS specific and used by getEnvironmentVariables().
public File	Returns: the directory as a File. getWorkingDirectory() Return the working directory.
public static boolean	Returns: `true` if `exitValue` signals a failure. isFailure(int the exit value (return code) to be checked. exitValue) Checks whether `exitValue` signals a failure on the current system (OS specific).
public boolean	Returns: true if and only if the exit code is interpreted as a failure isFailure() Did this execute return in a failure.
public boolean	Returns: true if a watchdog had to kill the process. killedProcess() Test for an untimely death of the process.
public static Process	Returns: the process started. launch(Project the Project, only used for logging purposes, may be null. project, String[] the command to run. command, String[] the environment for the command. env, File the working directory for the command. dir, boolean use the built-in exec command for JDK 1.3 if available. useVM) Creates a process that runs a command.
private String[]	Returns: the patched environment. patchEnvironment() Patch the current environment with the new values from the user.
public static void	runCommand(Task The task that the command is part of. Used for logging task, String... The command to execute. cmdline) A utility method that runs an external command.
public void	setAntRun(Project the current project. project) Set the name of the antRun script using the project's value.
public void	setCommandline(String[] the commandline of the subprocess to launch. commandline) Sets the commandline of the subprocess to launch.
public void	setEnvironment(String[] array of Strings, each element of which has an environment variable settings in format key=value. env) Sets the environment variables for the subprocess to launch.
protected void	setExitValue(int exit value of the process. value) Set the exit value.
public void	setNewenvironment(boolean whether to propagate the process environment. newenv) Set whether to propagate the default environment or not.
public void	setSpawn(boolean if true you do not want Ant to wait for the end of the process. Has no influence in here, the calling task contains and acts accordingly spawn) Deprecated Set whether or not you want the process to be spawned.
public void	setStreamHandler(ExecuteStreamHandler ExecuteStreamHandler. streamHandler) Set the stream handler to use.
public void	setVMLauncher(boolean true if exec should launch through the VM, false if the shell should be used to launch the command. useVMLauncher) Launch this execution through the VM, where possible, rather than through the OS's shell.
public void	setWorkingDirectory(File the working directory of the process. wd) Sets the working directory of the process to execute.
public void	spawn() Starts a process defined by the command line.
public static String	Returns: the output stream as a string, read with special encodings in the case of z/os and os/400. toString(ByteArrayOutputStream the output stream that one wants to read. 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 void	waitFor(Process the process one wants to wait for. process) Wait for a given process.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

antWorkingDirectory	back to summary
private static String antWorkingDirectory

cmdl	back to summary
private String[] cmdl

env	back to summary
private String[] env

environmentCaseInSensitive	back to summary
private static boolean environmentCaseInSensitive Used for replacing env variables

exitValue	back to summary
private int exitValue

INVALID	back to summary
public static final int INVALID Invalid exit code. set to `Integer#MAX_VALUE`

newEnvironment	back to summary
private boolean newEnvironment

ONE_SECOND	back to summary
private static final int ONE_SECOND

procEnvironment	back to summary
private static Map<String, String> procEnvironment

processDestroyer	back to summary
private static ProcessDestroyer processDestroyer Used to destroy processes when the VM exits.

project	back to summary
private Project project

streamHandler	back to summary
private ExecuteStreamHandler streamHandler

useVMLauncher	back to summary
private boolean useVMLauncher Controls whether the VM is used to launch commands, where possible.

watchdog	back to summary
private final ExecuteWatchdog watchdog

workingDirectory	back to summary
private File workingDirectory

Execute	back to summary
public Execute() Creates a new execute object using `PumpStreamHandler` for stream handling.

Execute	back to summary
public Execute(ExecuteStreamHandler streamHandler) Creates a new execute object. Parameters streamHandler:ExecuteStreamHandler the stream handler used to handle the input and output streams of the subprocess.

Execute	back to summary
public Execute(ExecuteStreamHandler streamHandler, ExecuteWatchdog watchdog) Creates a new execute object. Parameters streamHandler:ExecuteStreamHandler the stream handler used to handle the input and output streams of the subprocess. watchdog:ExecuteWatchdog a watchdog for the subprocess or `null` to disable a timeout for the subprocess.

Method Detail

closeStreams back to summary

closeStreams	back to summary
public static void closeStreams(Process process) Close the streams belonging to the given Process. Parameters process:Process the `Process`.

public static void closeStreams(Process process)

Close the streams belonging to the given Process.

Parameters

process:Process: the Process.

execute back to summary

execute	back to summary
public int execute() throws IOException Runs a process defined by the command line and returns its exit status. Returns:int the exit status of the subprocess or `INVALID`. Exceptions IOException: The exception is thrown, if launching of the subprocess failed.

public int execute() throws IOException

Runs a process defined by the command line and returns its exit status.

Returns:int

the exit status of the subprocess or INVALID.

Exceptions

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

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

getCommandline

back to summary

public String[] getCommandline()

Returns the commandline used to create a subprocess.

Returns:String[]: the commandline used to create a subprocess.

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

getEnvironment

back to summary

public String[] getEnvironment()

Returns the environment used to create a subprocess.

Returns:String[]: the environment used to create a subprocess.

getEnvironmentVariables	back to summary
public static synchronized Map<String, String> getEnvironmentVariables() Find the list of environment variables for this process. Returns:Map<String, String> a map containing the environment variables. Since Ant 1.8.2

getEnvironmentVariables

back to summary

public static synchronized Map<String, String> getEnvironmentVariables()

Find the list of environment variables for this process.

Returns:Map<String, String>: a map containing the environment variables.
Since: Ant 1.8.2

getExitValue	back to summary
public int getExitValue() Query the exit value of the process. Returns:int the exit value or Execute.INVALID if no exit value has been received.

getExitValue

back to summary

public int getExitValue()

Query the exit value of the process.

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

getProcEnvCommand	back to summary
private static String[] getProcEnvCommand() This is the operation to get our environment. It is a notorious troublespot pre-Java1.5, and should be approached with extreme caution. Returns:String[] command and arguments to get our environment

getProcEnvCommand

back to summary

private static String[] getProcEnvCommand()

This is the operation to get our environment. It is a notorious troublespot pre-Java1.5, and should be approached with extreme caution.

Returns:String[]: command and arguments to get our environment

getProcEnvironment	back to summary
public static synchronized Vector<String> getProcEnvironment() Deprecated use #getEnvironmentVariables instead Find the list of environment variables for this process. Returns:Vector<String> a vector containing the environment variables. The vector elements are strings formatted like variable = value. Annotations @Deprecated

getProcEnvironment

back to summary

public static synchronized Vector<String> getProcEnvironment()

Deprecated

use #getEnvironmentVariables instead

Find the list of environment variables for this process.

Returns:Vector<String>

a vector containing the environment variables. The vector elements are strings formatted like variable = value.

Annotations

@Deprecated

getVMSLogicals back to summary

getVMSLogicals	back to summary
private static Map<String, String> getVMSLogicals(BufferedReader in) throws IOException This method is VMS specific and used by getEnvironmentVariables(). Parses VMS logicals from `in` and returns them as a Map. `in` is expected to be the output of "SHOW LOGICAL". The method takes care of parsing the output correctly as well as making sure that a logical defined in multiple tables only gets added from the highest order table. Logicals with multiple equivalence names are mapped to a variable with multiple values separated by a comma (,).

private static Map<String, String> getVMSLogicals(BufferedReader in) throws IOException

This method is VMS specific and used by getEnvironmentVariables(). Parses VMS logicals from in and returns them as a Map. in is expected to be the output of "SHOW LOGICAL". The method takes care of parsing the output correctly as well as making sure that a logical defined in multiple tables only gets added from the highest order table. Logicals with multiple equivalence names are mapped to a variable with multiple values separated by a comma (,).

getWorkingDirectory	back to summary
public File getWorkingDirectory() Return the working directory. Returns:File the directory as a File. Since Ant 1.7

getWorkingDirectory

back to summary

public File getWorkingDirectory()

Return the working directory.

Returns:File: the directory as a File.
Since: Ant 1.7

isFailure back to summary

isFailure	back to summary
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:int the exit value (return code) to be checked. Returns:boolean `true` if `exitValue` signals a failure.

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:int: the exit value (return code) to be checked.

Returns:boolean

true if exitValue signals a failure.

isFailure back to summary

isFailure	back to summary
public boolean isFailure() Did this execute return in a failure. Returns:boolean true if and only if the exit code is interpreted as a failure Since Ant1.7 See Also `isFailure(int)`

public boolean isFailure()

Did this execute return in a failure.

Returns:boolean: true if and only if the exit code is interpreted as a failure
Since: Ant1.7
See Also: isFailure(int)

killedProcess	back to summary
public boolean killedProcess() Test for an untimely death of the process. Returns:boolean true if a watchdog had to kill the process. Since Ant 1.5

killedProcess

back to summary

public boolean killedProcess()

Test for an untimely death of the process.

Returns:boolean: true if a watchdog had to kill the process.
Since: Ant 1.5

launch	back to summary
public static Process launch(Project project, String[] command, String[] env, File dir, boolean useVM) throws IOException Creates a process that runs a command. Parameters project:Project the Project, only used for logging purposes, may be null. command:String[] the command to run. env:String[] the environment for the command. dir:File the working directory for the command. useVM:boolean use the built-in exec command for JDK 1.3 if available. Returns:Process the process started. Exceptions IOException: forwarded from the particular launcher used. Since Ant 1.5

launch

back to summary

public static Process launch(Project project, String[] command, String[] env, File dir, boolean useVM) throws IOException

Creates a process that runs a command.

Parameters

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

Returns:Process

the process started.

Exceptions

IOException:: forwarded from the particular launcher used.

Since

Ant 1.5

patchEnvironment	back to summary
private String[] patchEnvironment() Patch the current environment with the new values from the user. Returns:String[] the patched environment.

patchEnvironment

back to summary

private String[] patchEnvironment()

Patch the current environment with the new values from the user.

Returns:String[]: the patched environment.

runCommand	back to summary
public static void runCommand(Task task, String... cmdline) throws BuildException A utility method that runs an external command. Writes the output and error streams of the command to the project log. Parameters task:Task The task that the command is part of. Used for logging cmdline:String[] The command to execute. Exceptions BuildException: if the command does not exit successfully.

runCommand

back to summary

public static void runCommand(Task task, String... cmdline) throws BuildException

A utility method that runs an external command. Writes the output and error streams of the command to the project log.

Parameters

task:Task: The task that the command is part of. Used for logging
cmdline:String[]: The command to execute.

Exceptions

BuildException:: if the command does not exit successfully.

setAntRun	back to summary
public void setAntRun(Project project) throws BuildException Set the name of the antRun script using the project's value. Parameters project:Project the current project. Exceptions BuildException: not clear when it is going to throw an exception, but it is the method's signature.

setAntRun

back to summary

public void setAntRun(Project project) throws BuildException

Set the name of the antRun script using the project's value.

Parameters

project:Project: the current project.

Exceptions

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

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

setCommandline

back to summary

public void setCommandline(String[] commandline)

Sets the commandline of the subprocess to launch.

Parameters

commandline:String[]: the commandline of the subprocess to launch.

setEnvironment	back to summary
public void setEnvironment(String[] env) Sets the environment variables for the subprocess to launch. Parameters env:String[] array of Strings, each element of which has an environment variable settings in format key=value.

setEnvironment

back to summary

public void setEnvironment(String[] env)

Sets the environment variables for the subprocess to launch.

Parameters

env:String[]: array of Strings, each element of which has an environment variable settings in format key=value.

setExitValue	back to summary
protected void setExitValue(int value) Set the exit value. Parameters value:int exit value of the process.

setExitValue

back to summary

protected void setExitValue(int value)

Set the exit value.

Parameters

value:int: exit value of the process.

setNewenvironment	back to summary
public void setNewenvironment(boolean newenv) Set whether to propagate the default environment or not. Parameters newenv:boolean whether to propagate the process environment.

setNewenvironment

back to summary

public void setNewenvironment(boolean newenv)

Set whether to propagate the default environment or not.

Parameters

newenv:boolean: whether to propagate the process environment.

setSpawn	back to summary
public void setSpawn(boolean spawn) Deprecated Set whether or not you want the process to be spawned. Default is not spawned. Parameters spawn:boolean if true you do not want Ant to wait for the end of the process. Has no influence in here, the calling task contains and acts accordingly Annotations @Deprecated Since Ant 1.6

setSpawn

back to summary

public void setSpawn(boolean spawn)

Deprecated

Set whether or not you want the process to be spawned. Default is not spawned.

Parameters

spawn:boolean: if true you do not want Ant to wait for the end of the process. Has no influence in here, the calling task contains and acts accordingly

Annotations

@Deprecated

Since

Ant 1.6

setStreamHandler	back to summary
public void setStreamHandler(ExecuteStreamHandler streamHandler) Set the stream handler to use. Parameters streamHandler:ExecuteStreamHandler ExecuteStreamHandler. Since Ant 1.6

setStreamHandler

back to summary

public void setStreamHandler(ExecuteStreamHandler streamHandler)

Set the stream handler to use.

Parameters

streamHandler:ExecuteStreamHandler: ExecuteStreamHandler.

Since

Ant 1.6

setVMLauncher	back to summary
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:boolean true if exec should launch through the VM, false if the shell should be used to launch the command.

setVMLauncher

back to summary

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:boolean: true if exec should launch through the VM, false if the shell should be used to launch the command.

setWorkingDirectory	back to summary
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:File the working directory of the process.

setWorkingDirectory

back to summary

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:File: the working directory of the process.

spawn	back to summary
public void spawn() throws IOException Starts a process defined by the command line. Ant will not wait for this process, nor log its output. Exceptions IOException: The exception is thrown, if launching of the subprocess failed. Since Ant 1.6

spawn

back to summary

public void spawn() throws IOException

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

Exceptions

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

Since

Ant 1.6

toString	back to summary
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:ByteArrayOutputStream the output stream that one wants to read. Returns:String the output stream as a string, read with special encodings in the case of z/os and os/400. Since Ant 1.5

toString

back to summary

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:ByteArrayOutputStream: the output stream that one wants to read.

Returns:String

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

Since

Ant 1.5

waitFor	back to summary
protected void waitFor(Process process) Wait for a given process. Parameters process:Process the process one wants to wait for.

waitFor

back to summary

protected void waitFor(Process process)

Wait for a given process.

Parameters

process:Process: the process one wants to wait for.

public Class Execute

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail