ExecTask (Apache Ant API)

java.lang.Object
- org.apache.tools.ant.ProjectComponent
- - org.apache.tools.ant.Task
  - - org.apache.tools.ant.taskdefs.ExecTask

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

ExecuteOn
```
public class ExecTask
extends Task
```
Executes a given command if the os platform is appropriate.

Since:

Ant 1.2

Field Summary

Fields
Modifier and Type	Field and Description
`protected Commandline`	`cmdl`
`protected boolean`	`failOnError`
`protected boolean`	`newEnvironment`
`protected Redirector`	`redirector`
`protected RedirectorElement`	`redirectorElement`

Fields inherited from class org.apache.tools.ant.Task
target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent
description, location, project

Constructor Summary

Constructors
Constructor and Description

ExecTask()
Create an instance.

ExecTask(Task owner)
create an instance that is helping another task.

Constructors
Constructor and Description
`ExecTask()` Create an instance.
`ExecTask(Task owner)` create an instance that is helping another task.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addConfiguredRedirector(RedirectorElement redirectorElement)` Add a `RedirectorElement` to this task.
`void`	`addEnv(Environment.Variable var)` Add an environment variable to the launched process.
`protected void`	`checkConfiguration()` Has the user set all necessary attributes?
`Commandline.Argument`	`createArg()` Adds a command-line argument.
`protected ExecuteStreamHandler`	`createHandler()` Create the StreamHandler to use with our Execute instance.
`protected ExecuteWatchdog`	`createWatchdog()` Create the Watchdog to kill a runaway process.
`void`	`execute()` Do the work.
`java.lang.String`	`getOs()` List of operating systems on which the command may be executed.
`java.lang.String`	`getOsFamily()` Restrict this execution to a single OS Family
`boolean`	`getResolveExecutable()` Indicates whether to attempt to resolve the executable to a file.
`protected boolean`	`isValidOs()` Is this the OS the user wanted?
`protected void`	`logFlush()` Flush the output stream - if there is one.
`protected void`	`maybeSetResultPropertyValue(int result)` Helper method to set result property to the passed in value if appropriate.
`protected Execute`	`prepareExec()` Create an Execute instance with the correct working directory set.
`protected java.lang.String`	`resolveExecutable(java.lang.String exec, boolean mustSearchPath)` The method attempts to figure out where the executable is so that we can feed the full path.
`protected void`	`runExec(Execute exe)` Run the command using the given Execute instance.
`protected void`	`runExecute(Execute exe)` A Utility method for this classes and subclasses to run an Execute instance (an external command).
`void`	`setAppend(boolean append)` Set whether output should be appended to or overwrite an existing file.
`void`	`setCommand(Commandline cmdl)` Sets a command line.
`void`	`setDir(java.io.File d)` Set the working directory of the process.
`void`	`setError(java.io.File error)` Set the File to which the error stream of the process should be redirected.
`void`	`setErrorProperty(java.lang.String errorProperty)` Sets the name of the property whose value should be set to the error of the process.
`void`	`setExecutable(java.lang.String value)` Set the name of the executable program.
`void`	`setFailIfExecutionFails(boolean flag)` Set whether to stop the build if program cannot be started.
`void`	`setFailonerror(boolean fail)` Fail if the command exits with a non-zero return code.
`void`	`setInput(java.io.File input)` Set the input file to use for the task.
`void`	`setInputString(java.lang.String inputString)` Set the string to use as input.
`void`	`setLogError(boolean logError)` Controls whether error output of exec is logged.
`void`	`setNewenvironment(boolean newenv)` Do not propagate old environment when new environment variables are specified.
`void`	`setOs(java.lang.String os)` List of operating systems on which the command may be executed.
`void`	`setOsFamily(java.lang.String osFamily)` Restrict this execution to a single OS Family
`void`	`setOutput(java.io.File out)` File the output of the process is redirected to.
`void`	`setOutputproperty(java.lang.String outputProp)` Sets the property name whose value should be set to the output of the process.
`void`	`setResolveExecutable(boolean resolveExecutable)` Set whether to attempt to resolve the executable to a file.
`void`	`setResultProperty(java.lang.String resultProperty)` Sets the name of a property in which the return code of the command should be stored.
`void`	`setSearchPath(boolean searchPath)` Set whether to search nested, then system PATH environment variables for the executable.
`void`	`setSpawn(boolean spawn)` Set whether or not you want the process to be spawned.
`void`	`setTimeout(java.lang.Integer value)` Set the timeout in milliseconds after which the process will be killed.
`void`	`setTimeout(java.lang.Long value)` Set the timeout in milliseconds after which the process will be killed.
`protected void`	`setupRedirector()` Set up properties on the redirector that we needed to store locally.
`void`	`setVMLauncher(boolean vmLauncher)` Set whether to launch new process with VM, otherwise use the OS's shell.

Methods inherited from class org.apache.tools.ant.Task
bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent
clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject

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

- Field Detail
  - failOnError
```
protected boolean failOnError
```
  - newEnvironment
```
protected boolean newEnvironment
```
  - cmdl
```
protected Commandline cmdl
```
  - redirector
```
protected Redirector redirector
```
  - redirectorElement
```
protected RedirectorElement redirectorElement
```
- Constructor Detail
  - ExecTask
```
public ExecTask()
```
    Create an instance. Needs to be configured by binding to a project.
  - ExecTask
```
public ExecTask(Task owner)
```
    create an instance that is helping another task. Project, OwningTarget, TaskName and description are all pulled out
    
    Parameters:
    
    owner - task that we belong to
- Method Detail
  - setSpawn
```
public void setSpawn(boolean spawn)
```
    Set whether or not you want the process to be spawned. Default is false.
    
    Parameters:
    
    spawn - if true you do not want Ant to wait for the end of the process.
    
    Since:
    
    Ant 1.6
  - setTimeout
```
public void setTimeout(java.lang.Long value)
```
    Set the timeout in milliseconds after which the process will be killed.
    
    Parameters:
    
    value - timeout in milliseconds.
    
    Since:
    
    Ant 1.5
  - setTimeout
```
public void setTimeout(java.lang.Integer value)
```
    Set the timeout in milliseconds after which the process will be killed.
    
    Parameters:
    
    value - timeout in milliseconds.
  - setExecutable
```
public void setExecutable(java.lang.String value)
```
    Set the name of the executable program.
    
    Parameters:
    
    value - the name of the executable program.
  - setDir
```
public void setDir(java.io.File d)
```
    Set the working directory of the process.
    
    Parameters:
    
    d - the working directory of the process.
  - setOs
```
public void setOs(java.lang.String os)
```
    List of operating systems on which the command may be executed.
    
    Parameters:
    
    os - list of operating systems on which the command may be executed.
  - getOs
```
public final java.lang.String getOs()
```
    List of operating systems on which the command may be executed.
    
    Returns:
    
    String
    
    Since:
    
    Ant 1.8.0
  - setCommand
```
public void setCommand(Commandline cmdl)
```
    Sets a command line.
    
    Parameters:
    
    cmdl - command line.
  - setOutput
```
public void setOutput(java.io.File out)
```
    File the output of the process is redirected to. If error is not redirected, it too will appear in the output.
    
    Parameters:
    
    out - name of a file to which output should be sent.
  - setInput
```
public void setInput(java.io.File input)
```
    Set the input file to use for the task.
    
    Parameters:
    
    input - name of a file from which to get input.
  - setInputString
```
public void setInputString(java.lang.String inputString)
```
    Set the string to use as input.
    
    Parameters:
    
    inputString - the string which is used as the input source.
  - setLogError
```
public void setLogError(boolean logError)
```
    Controls whether error output of exec is logged. This is only useful when output is being redirected and error output is desired in the Ant log.
    
    Parameters:
    
    logError - set to true to log error output in the normal ant log.
  - setError
```
public void setError(java.io.File error)
```
    Set the File to which the error stream of the process should be redirected.
    
    Parameters:
    
    error - a file to which stderr should be sent.
    
    Since:
    
    Ant 1.6
  - setOutputproperty
```
public void setOutputproperty(java.lang.String outputProp)
```
    Sets the property name whose value should be set to the output of the process.
    
    Parameters:
    
    outputProp - name of property.
  - setErrorProperty
```
public void setErrorProperty(java.lang.String errorProperty)
```
    Sets the name of the property whose value should be set to the error of the process.
    
    Parameters:
    
    errorProperty - name of property.
    
    Since:
    
    Ant 1.6
  - setFailonerror
```
public void setFailonerror(boolean fail)
```
    Fail if the command exits with a non-zero return code.
    
    Parameters:
    
    fail - if true fail the command on non-zero return code.
  - setNewenvironment
```
public void setNewenvironment(boolean newenv)
```
    Do not propagate old environment when new environment variables are specified.
    
    Parameters:
    
    newenv - if true, do not propagate old environment when new environment variables are specified.
  - setResolveExecutable
```
public void setResolveExecutable(boolean resolveExecutable)
```
    Set whether to attempt to resolve the executable to a file.
    
    Parameters:
    
    resolveExecutable - if true, attempt to resolve the path of the executable.
  - setSearchPath
```
public void setSearchPath(boolean searchPath)
```
    Set whether to search nested, then system PATH environment variables for the executable.
    
    Parameters:
    
    searchPath - if true, search PATHs.
  - getResolveExecutable
```
public boolean getResolveExecutable()
```
    Indicates whether to attempt to resolve the executable to a file.
    
    Returns:
    
    the resolveExecutable flag
    
    Since:
    
    Ant 1.6
  - addEnv
```
public void addEnv(Environment.Variable var)
```
    Add an environment variable to the launched process.
    
    Parameters:
    
    var - new environment variable.
  - createArg
```
public Commandline.Argument createArg()
```
    Adds a command-line argument.
    
    Returns:
    
    new command line argument created.
  - setResultProperty
```
public void setResultProperty(java.lang.String resultProperty)
```
    Sets the name of a property in which the return code of the command should be stored. Only of interest if failonerror=false.
    
    Parameters:
    
    resultProperty - name of property.
    
    Since:
    
    Ant 1.5
  - maybeSetResultPropertyValue
```
protected void maybeSetResultPropertyValue(int result)
```
    Helper method to set result property to the passed in value if appropriate.
    
    Parameters:
    
    result - value desired for the result property value.
  - setFailIfExecutionFails
```
public void setFailIfExecutionFails(boolean flag)
```
    Set whether to stop the build if program cannot be started. Defaults to true.
    
    Parameters:
    
    flag - stop the build if program cannot be started.
    
    Since:
    
    Ant 1.5
  - setAppend
```
public void setAppend(boolean append)
```
    Set whether output should be appended to or overwrite an existing file. Defaults to false.
    
    Parameters:
    
    append - if true append is desired.
    
    Since:
    
    1.30, Ant 1.5
  - addConfiguredRedirector
```
public void addConfiguredRedirector(RedirectorElement redirectorElement)
```
    Add a RedirectorElement to this task.
    
    Parameters:
    
    redirectorElement - RedirectorElement.
    
    Since:
    
    Ant 1.6.2
  - setOsFamily
```
public void setOsFamily(java.lang.String osFamily)
```
    Restrict this execution to a single OS Family
    
    Parameters:
    
    osFamily - the family to restrict to.
  - getOsFamily
```
public final java.lang.String getOsFamily()
```
    Restrict this execution to a single OS Family
    
    Returns:
    
    the family to restrict to.
    
    Since:
    
    Ant 1.8.0
  - resolveExecutable
```
protected java.lang.String resolveExecutable(java.lang.String exec,
                                             boolean mustSearchPath)
```
    The method attempts to figure out where the executable is so that we can feed the full path. We first try basedir, then the exec dir, and then fallback to the straight executable name (i.e. on the path).
    
    Parameters:
    
    exec - the name of the executable.
    
    mustSearchPath - if true, the executable will be looked up in the PATH environment and the absolute path is returned.
    
    Returns:
    
    the executable as a full path if it can be determined.
    
    Since:
    
    Ant 1.6
  - execute
```
public void execute()
             throws BuildException
```
    Do the work.
    Overrides:
    
    execute in class Task
    
    Throws:
    BuildException - in a number of circumstances:
    
    if failIfExecFails is set to true and the process cannot be started
    
    the java13command launcher can send build exceptions
    
    this list is not exhaustive or limitative
  - checkConfiguration
```
protected void checkConfiguration()
                           throws BuildException
```
    Has the user set all necessary attributes?
    
    Throws:
    
    BuildException - if there are missing required parameters.
  - setupRedirector
```
protected void setupRedirector()
```
    Set up properties on the redirector that we needed to store locally.
  - isValidOs
```
protected boolean isValidOs()
```
    Is this the OS the user wanted?
    Returns:
    boolean.
    
    true if the os and osfamily attributes are null.
    
    true if osfamily is set, and the os family and must match that of the current OS, according to the logic of Os.isOs(String, String, String, String), and the result of the os attribute must also evaluate true.
    
    true if os is set, and the system.property os.name is found in the os attribute,
    
    false otherwise.
  - setVMLauncher
```
public void setVMLauncher(boolean vmLauncher)
```
    Set whether to launch new process with VM, otherwise use the OS's shell. Default value is true.
    
    Parameters:
    
    vmLauncher - true if we want to launch new process with VM, false if we want to use the OS's shell.
  - prepareExec
```
protected Execute prepareExec()
                       throws BuildException
```
    Create an Execute instance with the correct working directory set.
    
    Returns:
    
    an instance of the Execute class.
    
    Throws:
    
    BuildException - under unknown circumstances.
  - runExecute
```
protected final void runExecute(Execute exe)
                         throws java.io.IOException
```
    A Utility method for this classes and subclasses to run an Execute instance (an external command).
    
    Parameters:
    
    exe - instance of the execute class.
    
    Throws:
    
    java.io.IOException - in case of problem to attach to the stdin/stdout/stderr streams of the process.
  - runExec
```
protected void runExec(Execute exe)
                throws BuildException
```
    Run the command using the given Execute instance. This may be overridden by subclasses.
    
    Parameters:
    
    exe - instance of Execute to run.
    
    Throws:
    
    BuildException - if the new process could not be started only if failIfExecFails is set to true (the default).
  - createHandler
```
protected ExecuteStreamHandler createHandler()
                                      throws BuildException
```
    Create the StreamHandler to use with our Execute instance.
    
    Returns:
    
    instance of ExecuteStreamHandler.
    
    Throws:
    
    BuildException - under unknown circumstances.
  - createWatchdog
```
protected ExecuteWatchdog createWatchdog()
                                  throws BuildException
```
    Create the Watchdog to kill a runaway process.
    
    Returns:
    
    instance of ExecuteWatchdog.
    
    Throws:
    
    BuildException - under unknown circumstances.
  - logFlush
```
protected void logFlush()
```
    Flush the output stream - if there is one.

Class ExecTask

Field Summary

Fields inherited from class org.apache.tools.ant.Task

Fields inherited from class org.apache.tools.ant.ProjectComponent

Constructor Summary

Method Summary

Methods inherited from class org.apache.tools.ant.Task

Methods inherited from class org.apache.tools.ant.ProjectComponent

Methods inherited from class java.lang.Object

Field Detail

failOnError

newEnvironment

cmdl

redirector

redirectorElement

Constructor Detail

ExecTask

ExecTask

Method Detail

setSpawn

setTimeout

setTimeout

setExecutable

setDir

setOs

getOs

setCommand

setOutput

setInput

setInputString

setLogError

setError

setOutputproperty

setErrorProperty

setFailonerror

setNewenvironment

setResolveExecutable

setSearchPath

getResolveExecutable

addEnv

createArg

setResultProperty

maybeSetResultPropertyValue

setFailIfExecutionFails

setAppend

addConfiguredRedirector

setOsFamily

getOsFamily

resolveExecutable

execute

checkConfiguration

setupRedirector

isValidOs

setVMLauncher

prepareExec

runExecute

runExec

createHandler

createWatchdog

logFlush