org.apache.tools.ant.taskdefs
Class ExecTask

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

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

protected Commandline	cmdl
protected boolean	failOnError
protected boolean	newEnvironment
protected Redirector	redirector
protected RedirectorElement	redirectorElement

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

description, location, target, taskName, taskType, wrapper

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

project

Constructor Summary

ExecTask()

Method Summary

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.
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 searchPath) 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) Sets 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) File the error stream of the process is redirected to.
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) Sets a flag 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 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	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) Sets a flag indicating 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	setSpawn(boolean spawn) set whether or not you want the process to be spawned default is not spawned
void	setTimeout(java.lang.Integer value) Timeout in milliseconds after which the process will be killed.
void	setTimeout(java.lang.Long value) 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) Sets a flag indicating if we want to launch new process with VM, otherwise use the OS's shell.

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

getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

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

getProject, setProject

Methods inherited from class java.lang.Object

clone, 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()

Method Detail

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

setTimeout

public void setTimeout(java.lang.Long value)

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)

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

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 send output to

setInput

public void setInput(java.io.File input)

Set the input to use for the task

Parameters:

input - name of a file to get input from

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)

File the error stream of the process is redirected to.

Parameters:

error - a file to which send stderr to

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)

Sets a flag indicating whether to attempt to resolve the executable to a file

Parameters:

resolveExecutable - if true, attempt to resolve the path of the executable

getResolveExecutable

public boolean getResolveExecutable()

Indicates whether to attempt to resolve the executable to a file

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)

Sets a flag 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)

Sets 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.

resolveExecutable

protected java.lang.String resolveExecutable(java.lang.String exec,
                                             boolean searchPath)

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 ther path).

Parameters:

exec - the name of the executable

searchPath - if true, the excutable 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 under which ant is running is matches one os in the os attribute or if the os attribute is null
• false otherwise.

setVMLauncher

public void setVMLauncher(boolean vmLauncher)

Sets a flag indicating if we want to launch new process with VM, otherwise use the OS's shell. Default value of the flag 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.