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.
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
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
To create a new Custom Selector, you have to create a class that
The easiest way to do that is through the convenience base class
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
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
elements, your custom selector could just implement the
interface rather than the full
interface. Using the latter will give you the most flexibility,
Note: If you inherit from
any selector container will perform a validation pass before calling
isSelected() method. Make sure that all
initialization is performed before the validation is done.
These are the selectors used by Ant itself. To implement one of
these, you will have to alter some of the classes contained within
First, create a class that implements
You can either choose to implement all methods yourself from
scratch, or you can extend
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,
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
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
a BuildException will be thrown with the contents of your error
validate() method also gives you a
last chance to check your settings for consistency because it
verifySettings(). Override this method and
setError() within it if you detect any
problems in how your selector is set up.
You may also want to override
add method for your selector in
This is an interface, so you will also have to add an implementation
for the method in the classes which implement it, namely
Once it is in there, it will be available everywhere that core
selectors are appropriate.
Got an idea for a new Selector Container? Creating a new one is
Create a new class that implements
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
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
Again, put an
add method for your container in
and its implementations
Copyright © 2002 Apache Software
Foundation. All rights Reserved.