Ant: The Definitive Guide

PatternSet DataType

While filesets group files together, patternsets group patterns. These are closely related concepts, because filesets rely on patterns to select files. The <patternset> element may appear as a target-level buildfile element (i.e., as a child of <project>), and later be referenced by its id. As shown in the previous examples, it may also appear as a nested element of <fileset>. Tasks that are implicit filesets also support nested <patternset> elements.

The <patternset> element supports four attributes: includes, excludes, includesfile, and excludesfile. These are described in the previous section on filesets. In addition to these attributes, patternsets allow the following nested elements:

0..n nested <include> and <exclude> elements

These support the following attributes:

name (all, String, Y)

The pattern to include or exclude.

if (all, String, N)

The name of a property. Ant will only use this pattern if the property is set.

unless (all, String, N)

The name of a property. Ant will only use this pattern if the property is not set.

0..n nested <includesfile> and <excludesfile> elements

These support the following attributes:

name (all, String, Y)

Name of a file containing include and exclude patterns, one per line.

if (all, String, N)

The name of a property. Ant will only read the file if the property is set.

unless (all, String, N)

The name of a property. Ant will only read the file if the property is not set.

Examples

We now present two uses of the patternset DataType. The first shows a patternset being used to copy a related group of files from one directory to another. The second shows a patternset being used to conditionally include files in a compilation.

Copying files

The following is how we can set up a patternset to represent all XML-related filenames in a directory tree:

<patternset id="xml.files">
  <include name="**/*.dtd,**/*.xml,**/*.xslt"/>
</patternset>

Now we can use the copy task to copy these files from a source directory to a destination directory:

<copy todir="${deploy.dir}">
  <!-- select the files to copy -->
  <fileset dir="${src.dir}">
    <patternset refid="${xml.files}"/>
  </fileset>
</copy>

Conditionally including files

In this next example, we exclude all unit tests unless the includetests property is set:

<?xml version="1.0"?>
<project name="patternset_test_project" default="compile" basedir=".">

  <!-- exclude tests unless the 'includetests' property is set -->
  <patternset id="sources">
                  
    <include name="**/*.java"/>
                  
    <exclude name="**/*Test.java" unless="includetests"/>
                  
  </patternset>

  ...remainder of buildfile omitted

  <target name="compile" depends="prepare">
    <javac destdir="build">
      <!-- the directory from which the patternset finds files to compile -->
      <src path="src"/>

      <!-- refer to the patternset which selects the source files -->
      <patternset refid="sources"/>
    </javac>
  </target>

</project>

Now, to include unit tests in the build, we can set the includetests property when invoking Ant from the command line:

$ ant -Dincludetests=true compile