Tutorial: Tasks using Properties & Filesets

The goal

The goal is to write a task, which searchs in a path for a file and saves the location of that file in a property.

Build environment

We can use the buildfile from the other tutorial and modify it a little bit. Thatīs the advantage of using properties - we can reuse nearly the whole script. :-)

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="FindTask" basedir="." default="test">
    ...
    <target name="use.init" description="Taskdefī the Find-Task" depends="jar">
        <taskdef name="find" classname="Find" classpath="${ant.project.name}.jar"/>
    </target>

    <!-- the other use.* targets are deleted -->
    ...
</project>

Property access

Our first step is to set a property to a value and print the value of property. So our scenario would be

    <find property="test" value="test-value"/>
    <find print="test"/>

    <property name="test" value="test-value"/>
    <echo message="${test}"/>

So what to do? Handling three attributes (property, value, print) and an execute. Because this is only an introduction example I donīt do much checking:

import org.apache.tools.ant.BuildException;

public class Find extends Task {

    private String property;
    private String value;
    private String print;

    public void setProperty(String property) {
        this.property = property;
    }

    // setter for value and print

    public void execute() {
        if (print != null) {
            String propValue = getProject().getProperty(print);
            log(propValue);
        } else {
            if (property == null) throw new BuildException("property not set");
            if (value    == null) throw new BuildException("value not set");
            getProject().setNewProperty(property, value);
        }
    }
}

(by the way: a short word to ants "namespaces" (donīt be confused with xml namespaces which will be also introduces in the future (1.6 or 1.7): an <antcall> creates a new space for property names. All properties from the caller are passed to the callee, but the callee can set its own properties without notice by the caller.)

There are some other setter, too (but I havenīt used them, so I canīt say something to them, sorry :-)

After putting our two line example from above into a target names use.simple we can call that from our testcase:

import org.apache.tools.ant.BuildFileTest;

public class FindTest extends BuildFileTest {

    public FindTest(String name) {
        super(name);
    }

    public void setUp() {
        configureProject("build.xml");
    }

    public void testSimple() {
        expectLog("use.simple", "test-value");
    }
}

Using filesets

Ant provides a common way of bundling files: the fileset. Because you are reading this tutorial I think you know them and I donīt have to spend more explanations about their usage in buildfiles. Our goal is to search a file in path. And on this step the path is simply a fileset (or more precise: a collection of filesets). So our usage would be

    <find file="ant.jar" location="location.ant-jar">
        <fileset dir="${ant.home}" includes="**/*.jar"/>
    </find>

What do we need? A task with two attributes (file, location) and nested filesets. Because we had attribute handling already in the example above and the handling of nested elements is described in the other tutorial the code should be very easy:

public class Find extends Task {

    private String file;
    private String location;
    private Vector filesets = new Vector();

    public void setFile(String file) {
        this.file = file;
    }

    public void setLocation(String location) {
        this.location = location;
    }

    public void addFileset(FileSet fileset) {
        filesets.add(fileset);
    }

    public void execute() {
    }
}

In the other tutorial we have reused the already written targets of our buildfile. Now we will configure most of the testcases via java code (sometimes itīs much easier to write a target than doing it via java coding). What can be tested?

• not valid configured task (missing file, missing location, missing fileset)
• donīt find a present file
• behaviour if file canīt be found

public class FindTest extends BuildFileTest {

    ... // constructor, setUp as above

    public void testMissingFile() {
        Find find = new Find();
        try {
            find.execute();
            fail("No 'no-file'-exception thrown.");
        } catch (Exception e) {
            // exception expected
            String expected = "file not set";
            assertEquals("Wrong exception message.", expected, e.getMessage());
        }
    }

    public void testMissingLocation() {
        Find find = new Find();
        find.setFile("ant.jar");
        try {
            find.execute();
            fail("No 'no-location'-exception thrown.");
        } catch (Exception e) {
            ... // similar to testMissingFile()
        }
    }

    public void testMissingFileset() {
        Find find = new Find();
        find.setFile("ant.jar");
        find.setLocation("location.ant-jar");
        try {
            find.execute();
            fail("No 'no-fileset'-exception thrown.");
        } catch (Exception e) {
            ... // similar to testMissingFile()
        }
    }

    public void testFileNotPresent() {
        executeTarget("testFileNotPresent");
        String result = getProject().getProperty("location.ant-jar");
        assertNull("Property set to wrong value.", result);
    }

    public void testFilePresent() {
        executeTarget("testFilePresent");
        String result = getProject().getProperty("location.ant-jar");
        assertNotNull("Property not set.", result);
        assertTrue("Wrong file found.", result.endsWith("ant.jar"));
    }
}

If we run this test class all test cases (except testFileNotPresent) fail. No we can implement our task, so that these test cases will pass.

    protected void validate() {
        if (file==null) throw new BuildException("file not set");
        if (location==null) throw new BuildException("location not set");
        if (filesets.size()<1) throw new BuildException("fileset not set");
    }

    public void execute() {
        validate();                                                             // 1
        String foundLocation = null;
        for(Iterator itFSets = filesets.iterator(); itFSets.hasNext(); ) {      // 2
            FileSet fs = (FileSet)itFSets.next();
            DirectoryScanner ds = fs.getDirectoryScanner(getProject());         // 3
            String[] includedFiles = ds.getIncludedFiles();
            for(int i=0; i<includedFiles.length; i++) {
                String filename = includedFiles[i].replace('\\','/');           // 4
                filename = filename.substring(filename.lastIndexOf("/")+1);
                if (foundLocation==null && file.equals(filename)) {
                    File base  = ds.getBasedir();                               // 5
                    File found = new File(base, includedFiles[i]);
                    foundLocation = found.getAbsolutePath();
                }
            }
        }
        if (foundLocation!=null)                                                // 6
            getProject().setNewProperty(location, foundLocation);
    }

On //1 we check the prerequisites for our task. Doing that in a validate-method is a common way, because we separate the prerequisites from the real work. On //2 we iterate over all nested filesets. We we donīt want to handle multiple filesets, the addFileset() method has to reject the further calls. We can get the result of fileset via its DirectoryScanner like done //3. After that we create a plattform independend String representation of the file path (//4, can be done in other ways of course). We have to do the replace(), because we work with a simple string comparison. Ant itself is platform independant and can therefore run on filesystems with slash (/, e.g. Linux) or backslash (\, e.g. Windows) as path separator. Therefore we have to unify that. If we found our file we create an absolute path representation on //5, so that we can use that information without knowing the basedir. (This is very important on use with multiple filesets, because they can have different basedirs and the return value of the directory scanner is relative to its basedir.) Finally we store the location of the file as property, if we had found one (//6).

Ok, much more easier in this simple case would be to add the file as additional include element to all filesets. But I wanted to show how to handle complex situations whithout being complex :-)

The test case uses the ant property ant.home as reference. This property is set by the Launcher class which starts ant. We can use that property in our buildfiles as a build-in property (see [XXX]). But if we create a new ant environment we have to set that value for our own. And we use the <junit< task in fork-mode. Therefore we have do modify our buildfile:

    <target name="junit" description="Runs the unit tests" depends="jar">
        <delete dir="${junit.out.dir.xml}" />
        <mkdir  dir="${junit.out.dir.xml}" />
        <junit printsummary="yes" haltonfailure="no">
            <classpath refid="classpath.test"/>
            <sysproperty key="ant.home" value="${ant.home}"/>
            <formatter type="xml"/>
            <batchtest fork="yes" todir="${junit.out.dir.xml}">
                <fileset dir="${src.dir}" includes="**/*Test.java"/>
            </batchtest>
        </junit>
    </target>

Using nested paths

Returning a list

So far so good. But could a file be on more than one place in the path? - Of course.
And would it be good to get all of them? - It depends on ...

In this section we will extend that task to support returning a list of all files. Lists as property values are not supported by Ant natively. So we have to see how other tasks use lists. The most famous task using lists is Ant-Contribs <foreach>. All list elements are concatenated and separated with a customizable separator (default ',').

So we do the following:

    <find ... delimiter=""/> ... </find>

If the delimiter is set we will return all found files as list with that delimiter.

Therefore we have to

• provide a new attribute
• collect more than the first file
• delete duplicates
• create the list if necessary
• return that list

So we add as testcase:

in the buildfile:
    <target name="test.init">
        <mkdir dir="test1/dir11/dir111"/>                             *1
        <mkdir dir="test1/dir11/dir112"/>
        ...
        <touch file="test1/dir11/dir111/test"/>
        <touch file="test1/dir11/dir111/not"/>
        ...
        <touch file="test1/dir13/dir131/not2"/>
        <touch file="test1/dir13/dir132/test"/>
        <touch file="test1/dir13/dir132/not"/>
        <touch file="test1/dir13/dir132/not2"/>
        <mkdir dir="test2"/>
        <copy todir="test2">                                          *2
            <fileset dir="test1"/>
        </copy>
    </target>

    <target name="testMultipleFiles" depends="use.init,test.init">    *3
        <find file="test" location="location.test" delimiter=";">
            <path>
                <fileset dir="test1"/>
                <fileset dir="test2"/>
            </path>
        </find>
        <delete>                                                      *4
            <fileset dir="test1"/>
            <fileset dir="test2"/>
        </delete>
    </target>

in the test class:
    public void testMultipleFiles() {
        executeTarget("testMultipleFiles");
        String result = getProject().getProperty("location.test");
        assertNotNull("Property not set.", result);
        assertTrue("Only one file found.", result.indexOf(";") > -1);
    }

Now we need a directory structure where we CAN find files with the same name in different directories. Because we canīt sure to have one we create one on *1, *2. And of course we clean up that on *4. The creation can be done inside our test target or in a separate one, which will be better for reuse later (*3).

The task implementation is modified as followed:

    private Vector foundFiles = new Vector();
    ...
    private String delimiter = null;
    ...
    public void setDelimiter(String delim) {
        delimiter = delim;
    }
    ...
    public void execute() {
        validate();
        // find all files
        for(Iterator itPaths = paths.iterator(); itPaths.hasNext(); ) {
            Path path = (Path)itPaths.next();
            String[] includedFiles = path.list();
            for(int i=0; i<includedFiles.length; i++) {
                String filename = includedFiles[i].replace('\\','/');
                filename = filename.substring(filename.lastIndexOf("/")+1);
                if (file.equals(filename) && !foundFiles.contains(includedFiles[i])) {   // 1
                    foundFiles.add(includedFiles[i]);
                }
            }
        }

        // create the return value (list/single)
        String rv = null;
        if (foundFiles.size() > 0) {                                        // 2
            if (delimiter==null) {
                // only the first
                rv = (String)foundFiles.elementAt(0);
            } else {
                // create list
                StringBuffer list = new StringBuffer();
                for(Iterator it=foundFiles.iterator(); it.hasNext(); ) {    // 3
                    list.append(it.next());
                    if (it.hasNext()) list.append(delimiter);               // 4
                }
                rv = list.toString();
            }
        }

        // create the property
        if (rv!=null)
            getProject().setNewProperty(location, rv);
    }

The algorithm does: finding all files, creating the return value depending on the users wish, returning the value as property. On //1 we eliminates the duplicates. //2 ensures that we create the return value only if we have found one file. On //3 we iterate over all found files and //4 ensures that the last entry has no trailing delimiter.

Ok, first searching for all files and then returning only the first one ... You can tune the performance of your own :-)

Documentation

A task is useless if the only who is able to code the buildfile is the task developer (and he only the next few weeks :-). So documentation is also very important. In which form you do that depends on your favourite. But inside Ant there is a common format and it has advantages if you use that: all task users know that form, this form is requested if you decide to contribute your task. So we will doc our task in that form.

Contribute the new task

• is our task welcome? :-) Simply ask on the user list
• is the right package used?
• is the code conform to the styleguide?
• do all tests pass?
• does the code compile on JDK 1.2 (and passes all tests there)?
• code under Apache license
• create a patch file
• publishing that patch file

Resources