Top Description Fields Constructors Methods
org.apache.tools.ant.taskdefs

public Class ExecTask

extends Task
Class Inheritance
Known Direct Subclasses
org.apache.tools.ant.taskdefs.ExecuteOn
Imports
java.io.File, .IOException, java.util.Locale, .Map, org.apache.tools.ant.BuildException, .Project, .Task, org.apache.tools.ant.taskdefs.condition.Os, org.apache.tools.ant.types.Commandline, .Environment, .Path, .RedirectorElement, org.apache.tools.ant.util.FileUtils
Executes a given command if the os platform is appropriate.
Since
Ant 1.2

Field Summary

Modifier and TypeField and Description
protected Commandline
cmdl

private File
dir

private Environment
env

private File
error

private String
executable

private boolean
failIfExecFails

protected boolean
failOnError

private static final FileUtils
FILE_UTILS

private boolean
incompatibleWithSpawn

private File
input

private String
inputString

protected boolean
newEnvironment

private String
os

private String
osFamily

private File
output

protected Redirector
redirector

protected RedirectorElement
redirectorElement

private boolean
resolveExecutable

private String
resultProperty

private boolean
searchPath

private boolean
spawn

private Long
timeout

private boolean
vmLauncher

Controls whether the VM (1.3 and above) is used to execute the command

Inherited from org.apache.tools.ant.Task:
targettaskNametaskTypewrapper

Constructor Summary

AccessConstructor and Description
public
ExecTask()

Create an instance.

public
ExecTask(Task
task that we belong to
owner)

create an instance that is helping another task.

Method Summary

Modifier and TypeMethod and Description
public void
addConfiguredRedirector(RedirectorElement
RedirectorElement.
redirectorElement)

Add a RedirectorElement to this task.

public void
addEnv(Environment.Variable
new environment variable.
var)

Add an environment variable to the launched process.

protected void
checkConfiguration()

Has the user set all necessary attributes?

public Commandline.Argument

Returns:

new command line argument created.
createArg()

Adds a command-line argument.

protected ExecuteStreamHandler

Returns:

instance of ExecuteStreamHandler.
createHandler()

Create the StreamHandler to use with our Execute instance.

protected ExecuteWatchdog

Returns:

instance of ExecuteWatchdog.
createWatchdog()

Create the Watchdog to kill a runaway process.

public void
execute()

Overrides org.apache.tools.ant.Task.execute.

Do the work.
public final String

Returns:

String
getOs()

List of operating systems on which the command may be executed.

public final String

Returns:

the family to restrict to.
getOsFamily()

Restrict this execution to a single OS Family

private String
getPath(String line)

private String
getPath(Map<String, String> map)

public boolean

Returns:

the resolveExecutable flag
getResolveExecutable()

Indicates whether to attempt to resolve the executable to a file.

private boolean
isPath(String line)

protected boolean

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.
isValidOs()

Is this the OS the user wanted?

protected void
logFlush()

Flush the output stream - if there is one.

protected void
maybeSetResultPropertyValue(int
value desired for the result property value.
result)

Helper method to set result property to the passed in value if appropriate.

protected Execute

Returns:

an instance of the Execute class.
prepareExec()

Create an Execute instance with the correct working directory set.

protected String

Returns:

the executable as a full path if it can be determined.
resolveExecutable(String
the name of the executable.
exec, boolean
if true, the executable will be looked up in the PATH environment and the absolute path is returned.
mustSearchPath)

The method attempts to figure out where the executable is so that we can feed the full path.

protected void
runExec(Execute
instance of Execute to run.
exe)

Run the command using the given Execute instance.

protected final void
runExecute(Execute
instance of the execute class.
exe)

A Utility method for this classes and subclasses to run an Execute instance (an external command).

public void
setAppend(boolean
if true append is desired.
append)

Set whether output should be appended to or overwrite an existing file.

public void
setCommand(Commandline
command line.
cmdl)

Sets a command line.

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

Set the working directory of the process.

public void
setDiscardError(final boolean
if true error streams are discarded.
discard)

Whether error output should be discarded.

public void
setDiscardOutput(final boolean
if true output streams are discarded.
discard)

Whether output should be discarded.

public void
setError(File
a file to which stderr should be sent.
error)

Set the File to which the error stream of the process should be redirected.

public void
setErrorProperty(String
name of property.
errorProperty)

Sets the name of the property whose value should be set to the error of the process.

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

Set the name of the executable program.

public void
setFailIfExecutionFails(boolean
stop the build if program cannot be started.
flag)

Set whether to stop the build if program cannot be started.

public void
setFailonerror(boolean
if true fail the command on non-zero return code.
fail)

Fail if the command exits with a non-zero return code.

public void
setInput(File
name of a file from which to get input.
input)

Set the input file to use for the task.

public void
setInputString(String
the string which is used as the input source.
inputString)

Set the string to use as input.

public void
setLogError(boolean
set to true to log error output in the normal ant log.
logError)

Controls whether error output of exec is logged.

public void
setNewenvironment(boolean
if true, do not propagate old environment when new environment variables are specified.
newenv)

Do not propagate old environment when new environment variables are specified.

public void
setOs(String
list of operating systems on which the command may be executed.
os)

List of operating systems on which the command may be executed.

public void
setOsFamily(String
the family to restrict to.
osFamily)

Restrict this execution to a single OS Family

public void
setOutput(File
name of a file to which output should be sent.
out)

File the output of the process is redirected to.

public void
setOutputproperty(String
name of property.
outputProp)

Sets the property name whose value should be set to the output of the process.

public void
setResolveExecutable(boolean
if true, attempt to resolve the path of the executable.
resolveExecutable)

Set whether to attempt to resolve the executable to a file.

public void
setResultProperty(String
name of property.
resultProperty)

Sets the name of a property in which the return code of the command should be stored.

public void
setSearchPath(boolean
if true, search PATHs.
searchPath)

Set whether to search nested, then system PATH environment variables for the executable.

public void
setSpawn(boolean
if true you do not want Ant to wait for the end of the process.
spawn)

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

public void
setTimeout(Long
timeout in milliseconds.
value)

Set the timeout in milliseconds after which the process will be killed.

public void
setTimeout(Integer
timeout in milliseconds.
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.

public void
setVMLauncher(boolean
true if we want to launch new process with VM, false if we want to use the OS's shell.
vmLauncher)

Set whether to launch new process with VM, otherwise use the OS's shell.

Inherited from org.apache.tools.ant.Task:
bindToOwnergetOwningTargetgetRuntimeConfigurableWrappergetTaskNamegetTaskTypegetWrapperhandleErrorFlushhandleErrorOutputhandleFlushhandleInputhandleOutputinitisInvalidloglogloglogmaybeConfigureperformreconfiguresetOwningTargetsetRuntimeConfigurableWrappersetTaskNamesetTaskType

Field Detail

cmdlback to summary
protected Commandline cmdl
dirback to summary
private File dir
envback to summary
private Environment env
errorback to summary
private File error
executableback to summary
private String executable
failIfExecFailsback to summary
private boolean failIfExecFails
failOnErrorback to summary
protected boolean failOnError
FILE_UTILSback to summary
private static final FileUtils FILE_UTILS
incompatibleWithSpawnback to summary
private boolean incompatibleWithSpawn
inputback to summary
private File input
inputStringback to summary
private String inputString
newEnvironmentback to summary
protected boolean newEnvironment
osback to summary
private String os
osFamilyback to summary
private String osFamily
outputback to summary
private File output
redirectorback to summary
protected Redirector redirector
redirectorElementback to summary
protected RedirectorElement redirectorElement
resolveExecutableback to summary
private boolean resolveExecutable
resultPropertyback to summary
private String resultProperty
searchPathback to summary
private boolean searchPath
spawnback to summary
private boolean spawn
timeoutback to summary
private Long timeout
vmLauncherback to summary
private boolean vmLauncher

Controls whether the VM (1.3 and above) is used to execute the command

Constructor Detail

ExecTaskback to summary
public ExecTask()

Create an instance. Needs to be configured by binding to a project.

ExecTaskback to summary
public ExecTask(Task owner)

create an instance that is helping another task. Project, OwningTarget, TaskName and description are all pulled out

Parameters
owner:Task

task that we belong to

Method Detail

addConfiguredRedirectorback to summary
public void addConfiguredRedirector(RedirectorElement redirectorElement)

Add a RedirectorElement to this task.

Parameters
redirectorElement:RedirectorElement

RedirectorElement.

Since
Ant 1.6.2
addEnvback to summary
public void addEnv(Environment.Variable var)

Add an environment variable to the launched process.

Parameters
var:Environment.Variable

new environment variable.

checkConfigurationback to summary
protected void checkConfiguration() throws BuildException

Has the user set all necessary attributes?

Exceptions
BuildException:
if there are missing required parameters.
createArgback to summary
public Commandline.Argument createArg()

Adds a command-line argument.

Returns:Commandline.Argument

new command line argument created.

createHandlerback to summary
protected ExecuteStreamHandler createHandler() throws BuildException

Create the StreamHandler to use with our Execute instance.

Returns:ExecuteStreamHandler

instance of ExecuteStreamHandler.

Exceptions
BuildException:
under unknown circumstances.
createWatchdogback to summary
protected ExecuteWatchdog createWatchdog() throws BuildException

Create the Watchdog to kill a runaway process.

Returns:ExecuteWatchdog

instance of ExecuteWatchdog.

Exceptions
BuildException:
under unknown circumstances.
executeback to summary
public void execute() throws BuildException

Overrides org.apache.tools.ant.Task.execute.

Do the work.

Annotations
@Override
Exceptions
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
getOsback to summary
public final String getOs()

List of operating systems on which the command may be executed.

Returns:String

String

Since
Ant 1.8.0
getOsFamilyback to summary
public final String getOsFamily()

Restrict this execution to a single OS Family

Returns:String

the family to restrict to.

Since
Ant 1.8.0
getPathback to summary
private String getPath(String line)
getPathback to summary
private String getPath(Map<String, String> map)
getResolveExecutableback to summary
public boolean getResolveExecutable()

Indicates whether to attempt to resolve the executable to a file.

Returns:boolean

the resolveExecutable flag

Since
Ant 1.6
isPathback to summary
private boolean isPath(String line)
isValidOsback to summary
protected boolean isValidOs()

Is this the OS the user wanted?

Returns:boolean

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.
logFlushback to summary
protected void logFlush()

Flush the output stream - if there is one.

maybeSetResultPropertyValueback to summary
protected void maybeSetResultPropertyValue(int result)

Helper method to set result property to the passed in value if appropriate.

Parameters
result:int

value desired for the result property value.

prepareExecback to summary
protected Execute prepareExec() throws BuildException

Create an Execute instance with the correct working directory set.

Returns:Execute

an instance of the Execute class.

Exceptions
BuildException:
under unknown circumstances.
resolveExecutableback to summary
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:String

the name of the executable.

mustSearchPath:boolean

if true, the executable will be looked up in the PATH environment and the absolute path is returned.

Returns:String

the executable as a full path if it can be determined.

Since
Ant 1.6
runExecback to summary
protected void runExec(Execute exe) throws BuildException

Run the command using the given Execute instance. This may be overridden by subclasses.

Parameters
exe:Execute

instance of Execute to run.

Exceptions
BuildException:
if the new process could not be started only if failIfExecFails is set to true (the default).
runExecuteback to summary
protected final void runExecute(Execute exe) throws IOException

A Utility method for this classes and subclasses to run an Execute instance (an external command).

Parameters
exe:Execute

instance of the execute class.

Exceptions
IOException:
in case of problem to attach to the stdin/stdout/stderr streams of the process.
setAppendback to summary
public void setAppend(boolean append)

Set whether output should be appended to or overwrite an existing file. Defaults to false.

Parameters
append:boolean

if true append is desired.

Since
1.30, Ant 1.5
setCommandback to summary
public void setCommand(Commandline cmdl)

Sets a command line.

Parameters
cmdl:Commandline

command line.

setDirback to summary
public void setDir(File d)

Set the working directory of the process.

Parameters
d:File

the working directory of the process.

setDiscardErrorback to summary
public void setDiscardError(final boolean discard)

Whether error output should be discarded.

Defaults to false.

Parameters
discard:boolean

if true error streams are discarded.

Since
Ant 1.10.10
See Also
setDiscardOutput
setDiscardOutputback to summary
public void setDiscardOutput(final boolean discard)

Whether output should be discarded.

Defaults to false.

Parameters
discard:boolean

if true output streams are discarded.

Since
Ant 1.10.10
See Also
setDiscardError
setErrorback to summary
public void setError(File error)

Set the File to which the error stream of the process should be redirected.

Parameters
error:File

a file to which stderr should be sent.

Since
Ant 1.6
setErrorPropertyback to summary
public void setErrorProperty(String errorProperty)

Sets the name of the property whose value should be set to the error of the process.

Parameters
errorProperty:String

name of property.

Since
Ant 1.6
setExecutableback to summary
public void setExecutable(String value)

Set the name of the executable program.

Parameters
value:String

the name of the executable program.

setFailIfExecutionFailsback to summary
public void setFailIfExecutionFails(boolean flag)

Set whether to stop the build if program cannot be started. Defaults to true.

Parameters
flag:boolean

stop the build if program cannot be started.

Since
Ant 1.5
setFailonerrorback to summary
public void setFailonerror(boolean fail)

Fail if the command exits with a non-zero return code.

Parameters
fail:boolean

if true fail the command on non-zero return code.

setInputback to summary
public void setInput(File input)

Set the input file to use for the task.

Parameters
input:File

name of a file from which to get input.

setInputStringback to summary
public void setInputString(String inputString)

Set the string to use as input.

Parameters
inputString:String

the string which is used as the input source.

setLogErrorback to summary
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:boolean

set to true to log error output in the normal ant log.

setNewenvironmentback to summary
public void setNewenvironment(boolean newenv)

Do not propagate old environment when new environment variables are specified.

Parameters
newenv:boolean

if true, do not propagate old environment when new environment variables are specified.

setOsback to summary
public void setOs(String os)

List of operating systems on which the command may be executed.

Parameters
os:String

list of operating systems on which the command may be executed.

setOsFamilyback to summary
public void setOsFamily(String osFamily)

Restrict this execution to a single OS Family

Parameters
osFamily:String

the family to restrict to.

setOutputback to summary
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:File

name of a file to which output should be sent.

setOutputpropertyback to summary
public void setOutputproperty(String outputProp)

Sets the property name whose value should be set to the output of the process.

Parameters
outputProp:String

name of property.

setResolveExecutableback to summary
public void setResolveExecutable(boolean resolveExecutable)

Set whether to attempt to resolve the executable to a file.

Parameters
resolveExecutable:boolean

if true, attempt to resolve the path of the executable.

setResultPropertyback to summary
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:String

name of property.

Since
Ant 1.5
setSearchPathback to summary
public void setSearchPath(boolean searchPath)

Set whether to search nested, then system PATH environment variables for the executable.

Parameters
searchPath:boolean

if true, search PATHs.

setSpawnback to summary
public void setSpawn(boolean spawn)

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

Parameters
spawn:boolean

if true you do not want Ant to wait for the end of the process.

Since
Ant 1.6
setTimeoutback to summary
public void setTimeout(Long value)

Set the timeout in milliseconds after which the process will be killed.

Parameters
value:Long

timeout in milliseconds.

Since
Ant 1.5
setTimeoutback to summary
public void setTimeout(Integer value)

Set the timeout in milliseconds after which the process will be killed.

Parameters
value:Integer

timeout in milliseconds.

setupRedirectorback to summary
protected void setupRedirector()

Set up properties on the redirector that we needed to store locally.

setVMLauncherback to summary
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:boolean

true if we want to launch new process with VM, false if we want to use the OS's shell.