org.apache.tools.ant.taskdefs

Class ExecTask

public class ExecTask extends Task

Executes a given command if the os platform is appropriate.

Since: Ant 1.2

UNKNOWN: category="control"

Field Summary
protected Commandlinecmdl
protected booleanfailOnError
protected booleannewEnvironment
protected Redirectorredirector
protected RedirectorElementredirectorElement
Method Summary
voidaddConfiguredRedirector(RedirectorElement redirectorElement)
Add a RedirectorElement to this task.
voidaddEnv(Environment.Variable var)
Add an environment variable to the launched process.
protected voidcheckConfiguration()
Has the user set all necessary attributes?
Commandline.ArgumentcreateArg()
Adds a command-line argument.
protected ExecuteStreamHandlercreateHandler()
Create the StreamHandler to use with our Execute instance.
protected ExecuteWatchdogcreateWatchdog()
Create the Watchdog to kill a runaway process.
voidexecute()
Do the work.
booleangetResolveExecutable()
Indicates whether to attempt to resolve the executable to a file.
protected booleanisValidOs()
Is this the OS the user wanted?
protected voidlogFlush()
Flush the output stream - if there is one.
protected voidmaybeSetResultPropertyValue(int result)
Helper method to set result property to the passed in value if appropriate.
protected ExecuteprepareExec()
Create an Execute instance with the correct working directory set.
protected StringresolveExecutable(String exec, boolean mustSearchPath)
The method attempts to figure out where the executable is so that we can feed the full path.
protected voidrunExec(Execute exe)
Run the command using the given Execute instance.
protected voidrunExecute(Execute exe)
A Utility method for this classes and subclasses to run an Execute instance (an external command).
voidsetAppend(boolean append)
Set whether output should be appended to or overwrite an existing file.
voidsetCommand(Commandline cmdl)
Sets a command line.
voidsetDir(File d)
Set the working directory of the process.
voidsetError(File error)
Set the File to which the error stream of the process should be redirected.
voidsetErrorProperty(String errorProperty)
Sets the name of the property whose value should be set to the error of the process.
voidsetExecutable(String value)
Set the name of the executable program.
voidsetFailIfExecutionFails(boolean flag)
Set whether to stop the build if program cannot be started.
voidsetFailonerror(boolean fail)
Fail if the command exits with a non-zero return code.
voidsetInput(File input)
Set the input file to use for the task.
voidsetInputString(String inputString)
Set the string to use as input.
voidsetLogError(boolean logError)
Controls whether error output of exec is logged.
voidsetNewenvironment(boolean newenv)
Do not propagate old environment when new environment variables are specified.
voidsetOs(String os)
List of operating systems on which the command may be executed.
voidsetOutput(File out)
File the output of the process is redirected to.
voidsetOutputproperty(String outputProp)
Sets the property name whose value should be set to the output of the process.
voidsetResolveExecutable(boolean resolveExecutable)
Set whether to attempt to resolve the executable to a file.
voidsetResultProperty(String resultProperty)
Sets the name of a property in which the return code of the command should be stored.
voidsetSearchPath(boolean searchPath)
Set whether to search nested, then system PATH environment variables for the executable.
voidsetSpawn(boolean spawn)
Set whether or not you want the process to be spawned.
voidsetTimeout(Long value)
Set the timeout in milliseconds after which the process will be killed.
voidsetTimeout(Integer value)
Set the timeout in milliseconds after which the process will be killed.
protected voidsetupRedirector()
Set up properties on the redirector that we needed to store locally.
voidsetVMLauncher(boolean vmLauncher)
Set whether to launch new process with VM, otherwise use the OS's shell.

Field Detail

cmdl

protected Commandline cmdl

failOnError

protected boolean failOnError

newEnvironment

protected boolean newEnvironment

redirector

protected Redirector redirector

redirectorElement

protected RedirectorElement redirectorElement

Method Detail

addConfiguredRedirector

public void addConfiguredRedirector(RedirectorElement redirectorElement)
Add a RedirectorElement to this task.

Parameters: redirectorElement RedirectorElement.

Since: Ant 1.6.2

addEnv

public void addEnv(Environment.Variable var)
Add an environment variable to the launched process.

Parameters: var new environment variable.

checkConfiguration

protected void checkConfiguration()
Has the user set all necessary attributes?

Throws: BuildException if there are missing required parameters.

createArg

public Commandline.Argument createArg()
Adds a command-line argument.

Returns: new command line argument created.

createHandler

protected ExecuteStreamHandler createHandler()
Create the StreamHandler to use with our Execute instance.

Returns: instance of ExecuteStreamHandler.

Throws: BuildException under unknown circumstances.

createWatchdog

protected ExecuteWatchdog createWatchdog()
Create the Watchdog to kill a runaway process.

Returns: instance of ExecuteWatchdog.

Throws: BuildException under unknown circumstances.

execute

public void execute()
Do the work.

Throws: BuildException in a number of circumstances:

getResolveExecutable

public boolean getResolveExecutable()
Indicates whether to attempt to resolve the executable to a file.

Since: Ant 1.6

isValidOs

protected boolean isValidOs()
Is this the OS the user wanted?

Returns: boolean.

logFlush

protected void logFlush()
Flush the output stream - if there is one.

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.

prepareExec

protected Execute prepareExec()
Create an Execute instance with the correct working directory set.

Returns: an instance of the Execute class.

Throws: BuildException under unknown circumstances.

resolveExecutable

protected String resolveExecutable(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

runExec

protected void runExec(Execute exe)
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).

runExecute

protected final void runExecute(Execute exe)
A Utility method for this classes and subclasses to run an Execute instance (an external command).

Parameters: exe instance of the execute class.

Throws: IOException in case of problem to attach to the stdin/stdout/stderr streams of the process.

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

setCommand

public void setCommand(Commandline cmdl)
Sets a command line.

Parameters: cmdl command line.

UNKNOWN: ignore="true"

setDir

public void setDir(File d)
Set the working directory of the process.

Parameters: d the working directory of the process.

setError

public void setError(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

setErrorProperty

public void setErrorProperty(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

setExecutable

public void setExecutable(String value)
Set the name of the executable program.

Parameters: value the name of the executable program.

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

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.

setInput

public void setInput(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(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.

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.

setOs

public void setOs(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.

setOutput

public void setOutput(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.

setOutputproperty

public void setOutputproperty(String outputProp)
Sets the property name whose value should be set to the output of the process.

Parameters: outputProp name of property.

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.

setResultProperty

public void setResultProperty(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

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.

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(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(Integer value)
Set the timeout in milliseconds after which the process will be killed.

Parameters: value timeout in milliseconds.

setupRedirector

protected void setupRedirector()
Set up properties on the redirector that we needed to store locally.

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.

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