Ant: The Definitive Guide

FileList DataType

A filelist is a DataType supporting a named list of files, implemented by org.apache.tools.ant.types.FileList. The files do not have to exist in order to be included in a filelist. Following are the allowable attributes:

dir (1.4, File, *)

The directory used to compute absolute filenames.

files (1.4, String, *)

A comma-separated list of filenames.

refid (1.4, Reference, N)

A reference to a <filelist> defined elsewhere. The <filelist> being referred to defines a list of files. This is useful if you wish to define a list of files once, and then refer to it from several places in your buildfile.

Both dir and files are required, unless refid is specified, in which case neither dir nor files is allowed.

Example

The filelist DataType was introduced in Ant 1.4, along with the dependset task. (Since filelist is only used with dependset, we must talk about the dependset task to explain the filelist DataType). The dependset task compares one or more input files to one or more output files. If any of the input files are newer, then all of the output files are erased. Additionally, if any of the input files are missing, all of the output files are erased. Comparing output files to a set of input files that may not yet exist is why the filelist DataType is necessary.

Let’s illustrate why the combination of the filelist DataType and the dependset task is valuable. In this example, we are comparing a list of XML and XSLT files to a single HTML file. The HTML file, employeeDirectory.html, should be erased if any input file is missing or newer than it.

<?xml version="1.0"?>
<project name="filelist demo" default="xslt" basedir=".">

  <filelist id="stylesheets" dir="." files="header.xslt,footer.xslt,body.xslt"/>
               
  <filelist id="xmlfiles" dir="." files="employees.xml"/>

  <target name="xslt">
    <!-- erase employeeDirectory.html if any of the XML files or
         XSLT stylesheets are newer -->
    <dependset>
               
      <srcfilelist refid="stylesheets"/>
               
      <srcfilelist refid="xmlfiles"/>
               
      <targetfilelist dir="." files="employeeDirectory.html"/>
               
    </dependset>

    <echo message="Transforming Files..."/>
    ...
  </target>
</project>

employeeDirectory.html is dependent on four files: header.xslt, footer.xslt, body.xslt, and employees.xml. If any of these files are modified, employeeDirectory.html is erased by the dependset task. employeeDirectory.html is also erased if any of the input files are missing.

We defined two filelists, one for the XSLT files and another for the XML file. We could have just as easily defined a single filelist containing all files, although the buildfile is probably easier to understand if files are logically grouped together by type. We reference both of these filelists within the dependset task:

               
<dependset>
               
  <srcfilelist refid="stylesheets"/>
               
  <srcfilelist refid="xmlfiles"/>
               
  <targetfilelist dir="." files="employeeDirectory.html"/>
               
</dependset>

The <srcfilelist> tags use the refid attribute to refer back to the filelists defined earlier in the buildfile. The <targetfilelist> tag shows an alternate syntax, allowing the filelist to be defined inline. If you plan on referring to a filelist more than once in a buildfile, you should consider the refid approach. Otherwise, it is probably easier to define the filelist inline.

Tip

Although we are talking about the filelist DataType, the XML tags are called <srcfilelist> and <targetfilelist>. XML tag names frequently do not match DataType names.