Programming Selectors in Ant

Programming your own Selectors

Selector Programming API

Want to define your own selectors? It's easy!

First, pick the type of selector that you want to define. There are three types, and a recipe for each one follows. Chances are you'll want to work with the first one, Custom Selectors.

Custom Selectors

This is the category that Ant provides specifically for youto define your own Selectors. Anywhere you want to use your selector you use the <custom> element and specify the class name of your selector within it. See the Custom Selectors section of the Selector page for details. The <custom> element can be used anywhere the core selectors can be used. It can be contained within Selector Containers, for example.

To create a new Custom Selector, you have to create a class that implements org.apache.tools.ant.types.selectors.ExtendFileSelector. The easiest way to do that is through the convenience base class org.apache.tools.ant.types.selectors.BaseExtendSelector, which provides all of the methods for supporting <param> tags. First, override the isSelected() method, and optionally the verifySettings() method. If your custom selector requires parameters to be set, you can also override the setParameters() method and interpret the parameters that are passed in any way you like. Several of the core selectors demonstrate how to do that because they can also be used as custom selectors.

Note: If you don't need to set variables on your selector with the the embedded <param> elements, your custom selector could just implement the org.apache.tools.ant.types.selectors.FileSelector interface rather than the full org.apache.tools.ant.types.selectors.ExtendFileSelector interface. Using the latter will give you the most flexibility, though.

Note: If you inherit from org.apache.tools.ant.types.selectors.BaseExtendSelector or org.apache.tools.ant.types.selectors.BaseSelector, any selector container will perform a validation pass before calling the isSelected() method. Make sure that all initialization is performed before the validation is done.

Core Selectors

These are the selectors used by Ant itself. To implement one of these, you will have to alter some of the classes contained within Ant.

First, create a class that implements org.apache.tools.ant.types.selectors.FileSelector. You can either choose to implement all methods yourself from scratch, or you can extend org.apache.tools.ant.types.selectors.BaseSelector instead, a convenience class that provides reasonable default behaviour for many methods.

There is only one method required. public boolean isSelected(File basedir, String filename, File file) is the real purpose of the whole exercise. It returns true or false depending on whether the given file should be selected from the list or not.

If you are using org.apache.tools.ant.types.selectors.BaseSelector there are also some predefined behaviours you can take advantage of. Any time you encounter a problem when setting attributes or adding tags, you can call setError(String errmsg) and the class will know that there is a problem. Then, at the top of your isSelected() method call validate() and a BuildException will be thrown with the contents of your error message. The validate() method also gives you a last chance to check your settings for consistency because it calls verifySettings(). Override this method and call setError() within it if you detect any problems in how your selector is set up.

You may also want to override toString().
Put an add method for your selector in org.apache.tools.ant.types.selectors.SelectorContainer. This is an interface, so you will also have to add an implementation for the method in the classes which implement it, namely org.apache.tools.ant.types.AbstractFileSet and org.apache.tools.ant.types.selectors.BaseSelectorContainer. Once it is in there, it will be available everywhere that core selectors are appropriate.

Selector Containers

Got an idea for a new Selector Container? Creating a new one is no problem:

Create a new class that implements org.apache.tools.ant.types.selectors.SelectorContainer. This will ensure that your new Container can access any new selectors that come along. Again, there is a convenience class available for you called org.apache.tools.ant.types.selectors.BaseSelectorContainer.
Implement the public boolean isSelected(String filename, File file) method to do the right thing. Chances are you'll want to iterate over the selectors under you, so use selectorElements() to get an iterator that will do that.
Again, put an add method for your container in org.apache.tools.ant.types.selectors.SelectorContainer and its implementations org.apache.tools.ant.types.AbstractFileSet and org.apache.tools.ant.types.selectors.BaseSelectorContainer.