Execute (Apache Ant API)

java.lang.Object
- org.apache.tools.ant.taskdefs.Execute

public class Execute
extends java.lang.Object

Runs an external program.

Since:: Ant 1.2

Field Summary

Fields
Modifier and Type Field and Description

static int INVALID
Invalid exit code.

Fields
Modifier and Type	Field and Description
`static int`	`INVALID` Invalid exit code.

Constructor Summary

Constructors
Constructor and Description
`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

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static void`	`closeStreams(java.lang.Process process)` Close the streams belonging to the given Process.
`int`	`execute()` Runs a process defined by the command line and returns its exit status.
`java.lang.String[]`	`getCommandline()` Returns the commandline used to create a subprocess.
`java.lang.String[]`	`getEnvironment()` Returns the environment used to create a subprocess.
`static java.util.Map<java.lang.String,java.lang.String>`	`getEnvironmentVariables()` Find the list of environment variables for this process.
`int`	`getExitValue()` Query the exit value of the process.
`static java.util.Vector<java.lang.String>`	`getProcEnvironment()` Deprecated. use #getEnvironmentVariables instead
`java.io.File`	`getWorkingDirectory()` Return the working directory.
`boolean`	`isFailure()` Did this execute return in a failure.
`static boolean`	`isFailure(int exitValue)` Checks whether `exitValue` signals a failure on the current system (OS specific).
`boolean`	`killedProcess()` Test for an untimely death of the process.
`static java.lang.Process`	`launch(Project project, java.lang.String[] command, java.lang.String[] env, java.io.File dir, boolean useVM)` Creates a process that runs a command.
`static void`	`runCommand(Task task, java.lang.String[] cmdline)` A utility method that runs an external command.
`void`	`setAntRun(Project project)` Set the name of the antRun script using the project's value.
`void`	`setCommandline(java.lang.String[] commandline)` Sets the commandline of the subprocess to launch.
`void`	`setEnvironment(java.lang.String[] env)` Sets the environment variables for the subprocess to launch.
`protected void`	`setExitValue(int value)` Set the exit value.
`void`	`setNewenvironment(boolean newenv)` Set whether to propagate the default environment or not.
`void`	`setSpawn(boolean spawn)` Deprecated.
`void`	`setStreamHandler(ExecuteStreamHandler streamHandler)` Set the stream handler to use.
`void`	`setVMLauncher(boolean useVMLauncher)` Launch this execution through the VM, where possible, rather than through the OS's shell.
`void`	`setWorkingDirectory(java.io.File wd)` Sets the working directory of the process to execute.
`void`	`spawn()` Starts a process defined by the command line.
`static java.lang.String`	`toString(java.io.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 void`	`waitFor(java.lang.Process process)` Wait for a given process.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - INVALID
```
public static final int INVALID
```
    Invalid exit code. set to Integer.MAX_VALUE
    
    See Also:
    
    Constant Field Values
- 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 disable a timeout for the subprocess.
- Method Detail
  - setSpawn
```
@Deprecated
public void setSpawn(boolean spawn)
```
    Deprecated.
    
    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. Has no influence in here, the calling task contains and acts accordingly
    
    Since:
    
    Ant 1.6
  - getEnvironmentVariables
```
public static java.util.Map<java.lang.String,java.lang.String> getEnvironmentVariables()
```
    Find the list of environment variables for this process.
    
    Returns:
    
    a map containing the environment variables.
    
    Since:
    
    Ant 1.8.2
  - getProcEnvironment
```
@Deprecated
public static java.util.Vector<java.lang.String> getProcEnvironment()
```
    Deprecated. use #getEnvironmentVariables instead
    
    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.
  - toString
```
public static java.lang.String toString(java.io.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
  - setStreamHandler
```
public void setStreamHandler(ExecuteStreamHandler streamHandler)
```
    Set the stream handler to use.
    
    Parameters:
    
    streamHandler - ExecuteStreamHandler.
    
    Since:
    
    Ant 1.6
  - getCommandline
```
public java.lang.String[] getCommandline()
```
    Returns the commandline used to create a subprocess.
    
    Returns:
    
    the commandline used to create a subprocess.
  - setCommandline
```
public void setCommandline(java.lang.String[] commandline)
```
    Sets the commandline of the subprocess to launch.
    
    Parameters:
    
    commandline - the commandline of the subprocess to launch.
  - setNewenvironment
```
public void setNewenvironment(boolean newenv)
```
    Set whether to propagate the default environment or not.
    
    Parameters:
    
    newenv - whether to propagate the process environment.
  - getEnvironment
```
public java.lang.String[] getEnvironment()
```
    Returns the environment used to create a subprocess.
    
    Returns:
    
    the environment used to create a subprocess.
  - setEnvironment
```
public void setEnvironment(java.lang.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.
  - setWorkingDirectory
```
public void setWorkingDirectory(java.io.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.
  - getWorkingDirectory
```
public java.io.File getWorkingDirectory()
```
    Return the working directory.
    
    Returns:
    
    the directory as a File.
    
    Since:
    
    Ant 1.7
  - setAntRun
```
public void setAntRun(Project project)
               throws BuildException
```
    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.
  - 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.
  - launch
```
public static java.lang.Process launch(Project project,
                                       java.lang.String[] command,
                                       java.lang.String[] env,
                                       java.io.File dir,
                                       boolean useVM)
                                throws java.io.IOException
```
    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:
    
    java.io.IOException - forwarded from the particular launcher used.
    
    Since:
    
    Ant 1.5
  - execute
```
public int execute()
            throws java.io.IOException
```
    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.
  - spawn
```
public void spawn()
           throws java.io.IOException
```
    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
  - waitFor
```
protected void waitFor(java.lang.Process process)
```
    Wait for a given process.
    
    Parameters:
    
    process - the process one wants to wait for.
  - setExitValue
```
protected void setExitValue(int value)
```
    Set the exit value.
    
    Parameters:
    
    value - exit value of the process.
  - 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.
  - 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.
  - isFailure
```
public boolean isFailure()
```
    Did this execute return in a failure.
    
    Returns:
    
    true if and only if the exit code is interpreted as a failure
    
    Since:
    
    Ant1.7
    
    See Also:
    
    isFailure(int)
  - 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
  - runCommand
```
public static void runCommand(Task task,
                              java.lang.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 - The task that the command is part of. Used for logging
    
    cmdline - The command to execute.
    
    Throws:
    
    BuildException - if the command does not exit successfully.
  - closeStreams
```
public static void closeStreams(java.lang.Process process)
```
    Close the streams belonging to the given Process.
    
    Parameters:
    
    process - the Process.

Class Execute

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

INVALID

Constructor Detail

Execute

Execute

Execute

Method Detail

setSpawn

getEnvironmentVariables

getProcEnvironment

toString

setStreamHandler

getCommandline

setCommandline

setNewenvironment

getEnvironment

setEnvironment

setWorkingDirectory

getWorkingDirectory

setAntRun

setVMLauncher

launch

execute

spawn

waitFor

setExitValue

getExitValue

isFailure

isFailure

killedProcess

runCommand

closeStreams