Apache Jakarta and Beyond: A Java Programmeramp;#039;s Introduction [Electronic resources] نسخه متنی

2.3. Sets of Files as Task Arguments

Most parameters to tasks are provided as name/value pairs in the XML (Extensible Markup Language) node specifying the task. Some parameters are too complex to be represented by such pairs and must be provided as XML nodes within the task node.

The most common instance of this is specifying a set of files on which a task should act. For example, when compiling Java files typically the compilation should run over all .java files in all subdirectories within a given top-level directory. When generating javadocs it may be useful to omit certain directoriesfor example, those containing Java files that have been automatically generated by some other process. When building a Java file, usually only class files are included, but there may be special instances where images or other resources must also be included in the archive.

Ant provides a sophisticated mechanism for specifying sets of files. Normally this mechanism is used in conjunction with one of the built-in tasks, such as the one that performs compilation. To better see how this mechanism works independently of the tasks that use it, a minimal new task will be introduced. This task, called ls, processes a set of files by listing the full name of each. The last section in this chapter shows how the ls task was created and how other user-created tasks can access the same kind of information.

Along with the ls task the following examples will use the hypothetical directory structure shown in Figure 2.2; Listing 2.2 shows the initial build file.

Listing 2.2. A build file for exploring filesets

<project default="fileList">
<taskdef name="ls"
classname="com.awl.toolbook.chapter02.LsTask"/>
<target name="fileList">
<ls>
<fileset dir="."/>
</ls>
</target>
</project>

The first new element in this buildfile is the taskdef element at line two. This notifies Ant of the custom task by specifying the class that implements it and the name by which it can be used in targets.

When the ls task is used, it has no attributes, but it does have an inner node, fileset.fileset is the basic element used to construct lists of files; the only required attribute is dir, which in this example is set to "." indicating the current directory. With no other restrictions this will build a list containing every file and subdirectory within the specified dir. When Ant is run with this build file, it will produce the following output:

fileList:
[ls] build.xml
[ls] src/package1/autogen/table1.java
[ls] src/package1/autogen/table1.class
[ls] src/package1/autogen/table2.java
[ls] src/package1/autogen/table2.class
[ls] src/package1/class1.java
[ls] src/package1/class1.class
[ls] src/package1/class2.java
[ls] src/package1/class2.class
[ls] src/package2/class3.java
[ls] src/package2/class3.class
[ls] images/zim.jpg
[ls] images/dib.gif
[ls] images/gaz.jpg
[ls] doc/info/README
[ls] doc/info/config.txt
[ls] jars/ant.jar
[ls] jars/xml-apis.jar
BUILD SUCCESSFUL
Total time: 3 seconds

2.3.1. Including and Excluding Sets of Files

The set of files in a fileset can be finely controlled through use of the include and exclude elements. These elements work as their names imply when given individual files. If a fileset contains only include elements, then only the included files will be used. If the ls task in Listing 2.2 were replaced with

<ls>
<fileset dir=".">
<include name="src/package1/autogen/table1.java"/>
<include name="images/zim.jpg"/>
</fileset>
</ls>

then Ant would output

fileList:
[ls] src/package1/autogen/table1.java
[ls] images/zim.jpg

If a fileset contains only exclude elements, then the files named in these elements will be omitted from the list. Replacing the two include elements in the preceding example with <exclude name="doc/info/README"/> will output everything in the original list except for the README file.

It is also possible to specify include and exclude elements as attributes in the fileset node instead of as separate nested nodes. In this usage all elements appear in a single attribute separated by spaces. Using this syntax, the preceding example would be rewritten as

<fileset dir="."
includes="src/package1/autogen/table1.java
images/zim.jpg"/>

For the sake of clarity this book will only use the nested form, although the two are functionally equivalent.

2.3.2. Patterns

The include and exclude elements become even more powerful through the use of

patterns. These patterns resemble the wildcards used in DOS and Unix shells. For example,

<fileset dir=".">
<include name="src/package1/*.java"/>
</fileset>

will return all the java files in package1:

fileList:
[ls] src/package1/class1.java
[ls] src/package1/class2.java

Two consecutive asterisks in a pattern means "any number of directories," so <include name="**/*.java"/> will get all Java files throughout the project

fileList:
[ls] src/package1/autogen/table1.java
[ls] src/package1/autogen/table2.java
[ls] src/package1/class1.java
[ls] src/package1/class2.java
[ls] src/package2/class3.java

It is possible to combine include and exclude elements, as in

<fileset dir=".">
<include name="**/*.java"/>
<exclude name="**/autogen/*.java"/>
</fileset>

which would remove all the files from the autogen directory in the preceding list.

Ant does not process combinations of include and exclude elements sequentially; the order could be switched in the preceding example and the result would be the same. Rather, Ant works by matching all the patterns against the complete set of files. Any file that matches any of the includes and does not match any of the excludes is placed in the final list.

2.3.3. Other Tools to Build File Sets

It is possible to build sets of files based on criteria other than the names of the files. A set of files that contain a given string can be obtained with the contains element, which takes as an attribute the text to locate.^[2] Note that the string may not be a wildcard pattern or regular expression.^[3]

^{Chapter 13.}

This fileset specification

<fileset dir=".">
<contains text="Hello"/>
</fileset>

would return the following file list:

fileList:
[ls] build.xml
[ls] src/package2/class3.java
[ls] doc/info/README

It should not be surprising that the text "Hello" was deliberately placed in the README and class3.java files in order to demonstrate the functionality of the contains element. The presence of build.xml is more of a surprise because there is clearly no instance of "Hello" in Listing 2.2. However, if Listing 2.2 were modified to include the contains element, then "Hello"

would be present in the filein the very contains element that looks for "Hello." Therefore, build.xml has been added to this file list for the sake of realism.

The contains element combines with include in an obvious way; a file will make it to the final list if it is both in one of the included directories and it contains the specified text. For example, the preceding list could be restricted to just the README file by only including the documentation directories

<fileset dir=".">
<include name="doc/**/*"/>
<contains text="Hello"/>
</fileset>

Likewise, multiple contains elements in the same fileset provides a means to select only files that contain multiple specified strings.