Ant: The Definitive Guide

Path DataType

The path DataType appears frequently, and is sometimes referred to as a path-like structure. It may be used as an attribute or a nested element. It is most commonly used to represent a classpath, although it is also used to represent paths for other purposes. When used as an attribute, entries in the path are separated by semicolon (;) or colon (:) characters, which are replaced at build time with whatever path separator character the current platform prefers.

Tip

The path DataType, like others, is not always represented by the <path> XML element. For instance, the javac task accepts nested <classpath> elements that are implemented by the path DataType.

The path DataType offers a lot more flexibility when used as an XML element, rather than as an attribute. Following is a list of path attributes:

location (all, File, *)

Represents a single file or directory. Ant expands this into an absolute filename internally.^[31]

path (all, String, *)

A list of file and pathnames, delimited by ; or :.

refid (all, Reference, *)

A reference to a path defined elsewhere in the current buildfile. This is useful if you wish to refer to the same path definition from many places in the buildfile.

Both location and path are optional, unless refid is specified, in which case neither location nor path is allowed. You can’t have nested elements when refid is specified.

The path DataType also supports the following nested elements:

0..n nested <pathelement> elements^[32]

Defines one or more files to include in the path. Each nested <pathelement> also supports the location and path attributes, just like the containing path DataType.

0..n nested <fileset> elements

Provides another syntax for including files in the path.

0..n nested <path> elements

Recursively nests paths within other paths.

Here is how a path-likestructurerepresents a path consisting of two JAR files and two directories. The path is built in the order listed in the buildfile:

<path>
  <pathelement location="${libdir}/servlet.jar"/>
  <pathelement location="${libdir}/logging.jar"/>
  <pathelement path="${builddir}"/>
  <pathelement path="${utilpath}"/>
</path>

The path DataType also supports an abbreviated syntax. For instance, suppose we are using the <classpath> element within a task to define a path:

<!-- The classpath element is implemented with the path DataType -->
<classpath>
  <pathelement path="${builddir}"/>
</classpath>

This can be abbreviated as follows:

<classpath path="${builddir}"/>

The location attribute works similarly. As a final variation, one or more filesets can be nested inside path-likestructures:

<classpath>
  <pathelement path="${builddir}"/>
  <fileset dir="${libdir}" includes="**/*.jar"/>
</classpath>

In this example, the fileset includes all .jar files in all directories underneath the directory specified by ${libdir}.

---

^[31] Ant handles the details of converting paths into forms compatible with whatever operating system you are running on.

^[32] <pathelement> is implemented by PathElement, a nested class within org.apache.tools.ant.types.Path. It is a helper class rather than a DataType.