org.apache.tools.ant.taskdefs
Class ExecTask

java.lang.Object
  extended by org.apache.tools.ant.ProjectComponent
      extended by org.apache.tools.ant.Task
          extended by 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
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
ExecTask()
          Create an instance.
ExecTask(Task owner)
          create an instance that is helping another task.
 
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.
 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.

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

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.