Professional Java Tools for Extreme Programming: Ant, XDoclet, JUnit, Cactus, and Maven (Programmer to Programmer)

Ant Key Tasks

A key task is something that must be done for Ant. In contrast, most other tasks have more to do with accomplishing things for the application we are building.

Ant Task

The ant task executes an Ant buildfile from the currently executing Ant script:

<ANT antfile="[ant file name]"/>

It will execute the projects default target.

Parameters

• antfile*: The name of the Ant file to execute; defaults to build.xml.

• dir: The directory where the Ant file is located The root path of this file is specified in the project tags basedir parameter, at the beginning of the Ant file.

  <ANT antfile="[ant file] dir="[location of ant file]"/>

• target: A specific target to be run, located in the Ant file:

  <ANT antfile="[ant file] target="[target]"/>

• output: A file to hold the output of the Ant script:

  <ANT antfile="[ant file] output="[log file]"/>

Antcall Task

The antcall task executes an Ant target:

<antcall target="[target]"/>

All of the dependent Ant targets will execute, followed by the specific target specified.

Parameters

• target*: The target name that antcall will execute.

Nested Parameters

• param: A property to be set before running the tasks in the target.

• name: Name of a property to be assigned a value.

• value: Value to assign to the property.

This example will set a property to a value when the antcall task is executed:

<antcall target="[target name]"> <param name="[property]" value="[property value]"/> </antcall>

Available Task

You can use the available task to determine if a file, class, or Java Virtual Machine (JVM) system property is available. If it is not present, the task sets the value of a given property to false (the value defaults to true).

In the following example, if the file is not available, the property will be set to false:

<available file="[resource]" property="[property]"/>

Parameters

• property*: Name of the property to set, as defined by the property task.

• value: The text that will be assigned to the property if the resource is available. The default value is true:

  <available file="[file name]" property="[property]" value="[property value]"/>

• classname: Name of a class file; used to determine if the class file is available:

  <available classname="[class file]" property="[property]"/>

• resource: Name of a JVM resource; used to determine if the resource is available:

  <available resource ="[JVM Resource]" property="[property]"/>

• file*: Name of a file; used to determine if the file is available.

• classpath: A class path to use when looking up class files with the classname attribute:

  <available classpath="[class path]" classname="[class file]"/>

• classpathref: A classpathref is used to look into a classpath that has already been defined with a path element demonstrated in the buildfile snippet below.

  The following example will determine if a class file within a given path exists, by using the property that references a path:

  <project <path id="[property]"> <pathelement path="[path]/"/> </path> <task <available classname="[class file]" classpathref="[property of path]"/> </task>

Nested Parameter

• classpath: Allows tasks to use paths and class paths efficiently (see section Frequently Used Nested Parameters and Elements at the end of this chapter).

Echo Task

The echo task sends message to Ants system output or to a specified file:

<echo message="Hello world"/> <echo> This is a longer message stretching over two lines. </echo>

Parameters

• message*: Text of the message to display.

• file: Name of a file to direct output to.

• append: Boolean value of true or false. When set to true, output will be appended to a file specified by the file element. Defaults to false.

Fail Task

The fail task stops execution of the current build:

<fail/>

Parameter

• message: Text of a message to be displayed when the fail task is executed.

Property Task

The property task creates properties by assigning values to names . Properties set outside the current Ant project cannot be reassigned in the current Ant project:

<property name="[property]" value="[property value]"/>

Parameters

• name*: A name to be assigned to a name/value pair.

• value*: A value to be assigned to a name/value pair.

• refid: A name used in referring to an attribute specified by the id parameter of a path structure (see the path element in the section Ant Parent Elements):

  <property refid="[property]"/>

• file: A reference to an external properties file in which each line specifies a new key value pair:

  <property file="[file name]"/>

• location: A reference to an external properties file with an absolute path, in which each line specifies a new key value pair in the file:

  <property location="[absolute path]"/>

• environment: A prefix to be assigned to the property used to get the current systems properties:

  <property environment="[property]"/>

  The following line will return the value of the system property:

  <echo message="[environment property].[system property]"

• classpath: The class path used to determine the properties file for the java.util.Properties class in Suns JDK.

• classpathref: The class path defined in Ants path element that is used to determine the properties file for the java.util.Properties class in Suns JDK.

Nested Parameter

• classpath: Allows tasks to use paths and class paths efficiently (see section Frequently Used Nested Parameters and Elements at the end of this chapter).

Taskdef Task

The taskdef task creates a custom task by executing Java classes:

<taskdef name="[task]" classname="[java class]"/>

Parameters

• name*: The name of the task.

• classname*: The full class name.

• classpath: The class path used when looking up the class name:

  <taskdef name="[task]" classname="[java class]" classpath"[classpath]"/>