External Execution Tasks

External execution tasks enable you to invoke other programs and shell scripts.

Apply Task

The apply, exec , and execon tasks all have similar functions, but it is useful to review their capabilities before you decide which one to use. Apply is the most complex of the three. It executes the specified program using both file sets and mappers. The file sets define a group of files that will be applied to the executable. The mapper allows for time and date checking to compare the source files times against the destination files, avoiding unnecessary execution of unwanted sources. The apply task is as follows :

 <apply executable="[command]" dest="[path]"/>

Parameters

executable*: File name of the executable.
dest*: Directory that holds the target files.
dir: The working directory of the system command.
os: List of operating systems on which the command will run.
output: A file to store the output of the command.
timeout: Amount of time after which execution will be halted, specified in milliseconds .
failonerror: If the program returns a code other then 0, the build will fail.
parallel: When set to true, files are appended as arguments rather than being executed individually. Defaults to false.
type: Value of file, dir, or both. The file command sends only file names as system commands. The dir command sends the directory name to be used to determine what files to execute. The both command uses file names and directory names . Defaults to file.

Nested Parameters

fileset: Specifies a collections of files (see section Frequently Used Nested Parameters and Elements at the end of this chapter for more information).
arg: Comand line arguments for the command.
srcfile: In cases where some arguments come befor and some are after the name of the soure files name, its relative poison can be marked with the srcfile tag.
```
 <apply executable=[file name]>   <arg value=[argument]/>   <srfile/>   <arg value=[argument]/>   <fileset dir=[path]/> </apply> 
```
targetfile: Uses the dest parameter of the apply task to find files to be used as targets. Like the srcfile nested task is marks the location of the targeted files within command line arguments.
env: Specifies values available at run time.
- key: Name of the environmental variable.
- value: Value of the environmental variable.
- path: A path value to use with a key.
- file: A file to use with a given command.
- mapper: A definition can be found under the Frequently Used Nested Parameters section at the end of this chapter.

Exec Task

As we mentioned earlier, the apply, exec, and execon tasks have similar functions. Exec is the simplest of the threeit simply executes the specified program:

 <exec executable="[commad and switches]"/>

Parameters

command*: The whole command line as it would be executed, with all its parameters, on the system.
executable: File name of the executable.
dir: Working directory of the system command.
os: List of operating systems on which the command will run.
output: File to store the output of the command.
timeout: Amount of time after which execution will be halted, specified in milliseconds.
failonerror: If the program returns a code other then 0, the build will fail.
newenvironment: When new environment variables are specified, does not propagate the old environment. Defaults to false.

Nested Parameters

arg: Comand line arguments for the command.
env: Specifies values available at run time.
- key: Name of the environmental variable.
- value: Value of the environmental variable.
- path: A path value to use with a key.
- file: A file to use with a given command.
- mapper: A definition can be found under the Frequently Used Nested Parameters section.

Execon Task

As weve mentioned, the apply, exec, and execon tasks have similar functions. Execons complexity falls between the other two. It executes the specified program and allows for filesets to be used. The filesets define a group of files that can be applied to the executable:

 <execon executable="[command]">   <fileset dir="[directory]" includes="[pateren set]"/> </apply>

Parameters

executable*: File name of the executable.
dir: The working directory of the system command.
os: List of operating systems on which the command will run.
output: File to store the output of the command.
timeout: Amount of time after which execution will be halted, specified in milliseconds.
failonerror: If the program returns a code other then 0, the build will fail.
newenvironment: When new environment variables are specified, does not propagate the old environment. Defaults to false.
parallel: When set to true, files are appended as arguments rather than being executed individually. Defaults to false.
type: Value of file, dir, or both. The file: command sends only file names as system commands. The dir command sends the directory name to be used to determine what files to execute. The both command uses file names and directory names. Defaults to file.

Nested Parameters

fileset: Specifies a collections of files (see section Frequently Used Nested Parameters and Elements at the end of this chapter for more information).
arg: Comand line arguments for the command. srcfilecom . In cases where some arguments come befor and some are after the name of the soure files name, its relative poison can be marked with the srcfile tag.
```
 <apply executable=[file name]>   <arg value=[argument]/>   <srfile/>   <arg value=[argument]/>   <fileset dir=[path]/> </apply> 
```
targetfile: Uses the dest parameter of the apply task to find files to be used as targets. Like the srcfile nested task is marks the location of the targeted files within command line arguments.
env: Specifies values available at run time.
- key: Name of the environmental variable.
- value: Value of the environmental variable.
- path: A path value to use with a key.
- file: A file to use with a given command.
- mapper: A definition can be found under the Frequently Used Nested Parameters section.

Java Task

The java task executes a Java class:

 <java classname="java class" />

This method of invoking the compiler has many useful options you can use to invoke a new JVM for the Java application to run in. In most cases, it is more robust to invoke a new JVM.

Parameters

classname*: The Java class to execute.
classpath: The class path for the Java program execution.
classpathref: A reference id to a class path for the Java program execution.
fork: Boolean value of yes and no. When set to yes, a new JVM will be instantiated . Defaults to no.
jvm: Used with the fork parameter. Invokes the Java compiler. Defaults to java.
jvmargs: Used with the fork parameter. Specifies parameters to pass when invoking the JVM.
maxmemory: Used with the fork parameter. The maximum amount of memory allocated to theJVM.
failonerror: Available only if fork is yes (true). Stops the build process if the command exits with a returncode other than 0.
dir: Used with the fork parameter. The working directory for the JVM.
output: A file to which to write the output of the JVM.

Nested Parameters

arg: Comand line arguments for the java application.
jvmarg: Comand line arguments for the JVM.
sysproperty: Specifies values available at run time.
- key: Name of the environmental variable.
- value: Value of the environmental variable.
- path: A path value to use with a key.
- file: A file to use with a given command.
- mapper: A definition can be found under the Frequently Used Nested Parameters section at the end of this chapter.
classpath: Allows tasks to use paths and class paths efficiently (see section Frequently Used Nested Parameters and Elements at the end of this chapter).

Javac Task

This command is used to compile Java source code using the JVM in which Ant is running:

 <javac srcdir="[directory]"/>

Parameters

src*: The directory where the Java packages to be compiled are located.
dirdestdir: The location where the class files will be placed after they are successfully compiled.
includes: Comma-separated list of patterns to use with the src parameter.
includesfile: File in which each new line lists patterns to use with the src parameter.
excludes: Comma-separated list of patterns not to use with the src parameter.
excludesfile: File in which each new line lists patterns not to use with the src parameter.
defaultexcludes: A value of yes or no. Yes sets the default excludes to be used. Defaults to no.
classpath: Class path to be used by the compiler.
bootclasspath: Location of the bootstrap class files.
classpathref: Class path to be used by the compiler, specified as a reference ID.
bootclasspathref: Location of the bootstrap class files, specified as a reference ID.
extdirs: Location of installed extensions.
encoding: Encoding of source files.
debug: When set to no, debug information from the compiler will be shown as output. Defaults to off.
optimize: When set to on, the compiler is set to optimize its execution. Defaults to off.
deprecation : When set to on, deprecation information from the compiler will be shown as output. Defaults to off.
target: Tells the compiler to generate class files for a JVM version.
verbose: Tells the compiler to use verbose output.
depend: Tells the compiler to use dependency tracking, if it supports it.
includeANTRuntime: When set to no, the lib directory in the ANT_HOME directory will not be used as part of the class path. Defaults to yes.
includeJavaRuntime: When set to yes, the lib directory in the JAVA_HOME directory will be used as part of the class path. Defaults to no.
failonerror: When set to false, the compiler will continue even when it fails to compile a class. Defaults to true.

Nested Parameters

fileset: Specifies a collections of files (see section Frequently Used Nested Parameters and Elements at the end of this chapter for more information).
src: Same as srcdir in the javc task.
classpath: Same as classpath in the javac task.
bootclasspath: Same as bootclasspath in the javac task.
extdirs: Same as extdirs in the javac task.

Sql Task

The sql task executes SQL statements using a JBDC source:

 <sql     driver="[java class]"     url="[database url]"     userid="[user]"     password="[password]"     src="[file]" />

Commands can be executed without an src parameter file, as follows:

 <sql     driver=[java class]     url="[database url]"     userid="[user]"     password="[password]"     > select * from tablefoo insert into table foo values (1,2,3) </sql>

Parameters

driver: Java class name of the Java Database Connectivity (JDBC) driver.
url: Database connection URL.
userid: Database user name.
password: Database password.
src: File containing SQL statements separated by semicolons and commented with double slashes (//) or double dashes (--).
autocommit: When set to true, the transactions are committed after execution. Defaults to false.
print: When set to true, the output returned from the execution of the SQL statement is displayed. Defaults to false.
showheaders: When set to false, the headers will not be displayed out. Defaults to true.
output: File to write system out information to. Defaults to System.out.
classpath: Class path used to load the driver.
onerror: Value of continue, stop, or abort. Tells Ant how to handle errors. Continue shows the error, and execution is not interrupted . Stop halts execution of Ant, and transactions are committed. Abort stops execution of Ant, and transactions are not committed.
rdbms: Executes commands only if the JBDC driver returns that the RDBMS (Remote Database Message System) is equal to a given value.
version: Executes commands only if the JBDC driver returns that the RDBMS(Remote Database Message System) version is equal to a given value.

Nested Parameters

transaction: Executes several commands using the same connection.
src: File containing SQL statements separated by semicolons and commented with double slashes (//) or double dashes (--).
classpath: Allows tasks to use paths and class paths efficiently (see section Frequently Used Nested Parameters and Elements at the end of this chapter).