Ant: The Definitive Guide

XML Attribute Conventions

DataTypes, like tasks, are defined using attributes. As we discuss each DataType in this chapter, we also list all the available attributes for it. These listings describe each attribute, specify which versions of Ant support it, and indicate whether it is required. The attribute listings take on the following form:

attribute_name (version, type, required_flag)

Is a description of an attribute and its function.

In which:

attribute_name

Is the name of the attribute. Use this to refer to the attribute when you specify it for a task.

version

Indicates the version of Ant supporting this attribute. "all" means Ant Versions 1.2 and later.

type

Indicates the type of data that an attribute can hold. For example, String indicates that an attribute holds textual data. See Table 4-1.

required_flag

Indicates whether a given attribute is required when using the task. If this flag is a asterisk (*), then see the notes immediately following the list.

Description of attribute

Is a description of the attribute and its function.

Table 4-1 summarizes the attribute types frequently referenced throughout this chapter. In all cases, text from XML attributes is converted into one of the basic types listed here. The “Description” column describes how each conversion happens. The “Implemented by” column lists the Java class that Ant uses to represent each of these attribute types.

Table 4-1. XML attribute type summary

Type name	Implemented by	Description
boolean	N/A	Performs a case-insensitive string comparison, converting on, true, and yes to true. All other values are false.
Enum	org.apache.tools.ant.types.EnumeratedAttribute	Used in cases in which a fixed set of string values are allowed.
File	java.io.File	Specifies the name of an individual file or directory. Unless stated otherwise, file and directory names are relative to the project base directory. fileset and filelist, described shortly, allow you to specify multiple files.
int, long, etc...	N/A	The standard Java type wrapper classes like java.lang.Integer handle conversion from text in the buildfile to primitive types.
Path	org.apache.tools.ant.types.Path	Most commonly used by classpath and sourcepath attributes, representing a list of paths separated by :or;. This is described in detail under “Path DataType.”
Reference	org.apache.tools.ant.types.Reference	Commonly used in refid attributes, and contains a reference to a type defined elsewhere. See the example for the java task in Chapter 7, which shows how to reference a classpath defined elsewhere in the buildfile.
String	java.lang.String	The most commonly used type in Ant. Strings (along with other attributes) are subject to XML attribute limitations. For instance, the < character must be written as &lt;.