Selectors

Selectors are a mechanism whereby the files that make up a fileset can be selected based on criteria other than filename as provided by the <include> and <exclude> tags.

How to use a Selector

A selector is an element of FileSet, and appears within it. It can also be defined outside of any target by using the <select> tag and then using it as a reference.

Different selectors have different attributes. Some selectors can contain other selectors, and these are called Selector Containers. There is also a category of selectors that allow user-defined extensions, called Extend Selectors. The ones built in to Ant are called Static Selectors.

Static Selectors

Static selectors are the ones that come standard with Ant. They can be used within a fileset and can be contained within Selector Containers.

The static selectors are:

• <containsselect> - Select files that contain a particular text string
• <dateselect> - Select files that have been modified either before or after a particular date and time
• <dependselect> - Select files that have been modified more recently than equivalent files elsewhere
• <depthselect> - Select files that appear so many directories down in a directory tree
• <filenameselect> - Select files whose name matches a particular pattern. Equivalent to the include and exclude elements of a patternset.
• <presentselect> - Select files that either do or do not exist in some other location
• <sizeselect> - Select files that are larger or smaller than a particular number of bytes.

Contains Selector

The <containsselect> tag in a FileSet limits the files defined by that fileset to only those which contain the string specified by the contains attribute. .

Here is an example of how to use the Contains Selector:

<fileset dir="${doc.path}" includes="**/*.html">
    <containsselect contains="<script" casesensitive="no"/>
</fileset>

Selects all the HTML files that contain a <script> tag.

Date Selector

The <dateselect> tag in a FileSet will put a limit on the files specified by the include tag, so that tags whose last modified date does not meet the date limits specified by the selector will not end up being selected.

Here is an example of how to use the Date Selector:

<fileset dir="${jar.path}" includes="**/*.jar">
    <dateselect datetime="01/01/2001 12:00 AM" when="before"/>
</fileset>

Selects all JAR files which were last modified before midnight January 1, 2001.

Depend Selector

The <dependselect> tag selects files whose last modified date is later than another, equivalent file in another location.

The <dependselect> tag supports the use of a contained element to define the location of the file to be compared against. If no element is specified, the identity type mapper is used.

Here is an example of how to use the Depend Selector:

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <dependselect targetdir="${ant.1.4.1}/src/main"/>
</fileset>

Selects all the Java source files which were modified in the 1.5 release.

Depth Selector

The <depthselect> tag selects files based on how many directy levels deep they are in relation to the base directory of the fileset.

Here is an example of how to use the Depth Selector:

<fileset dir="${doc.path}" includes="**/*">
    <depthselect max="1"/>
</fileset>

Selects all files in the base directory and one directory below that.

Filename Selector

The <filenameselect> tag acts like the <include> and <exclude> tags within a fileset. By using a selector instead, however, one can combine it with all the other selectors using whatever selector container is desired.

Here is an example of how to use the Filename Selector:

<fileset dir="${doc.path}" includes="**/*">
    <filenameselect name="**/*.css"/>
</fileset>

Selects all the cascading style sheet files.

Present Selector

The <presentselect> tag selects files that have an equivalent file in another directory tree.

The <presentselect> tag supports the use of a contained element to define the location of the file to be tested against. If no element is specified, the identity type mapper is used.

Here is an example of how to use the Present Selector:

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <presentselect targetdir="${ant.1.4.1}/src/main"/>
</fileset>

Selects all the Java source files which are new in the 1.5 release.

Size Selector

The <sizeselect> tag in a FileSet will put a limit on the files specified by the include tag, so that tags which do not meet the size limits specified by the selector will not end up being selected.

Here is an example of how to use the Size Selector:

<fileset dir="${jar.path}">
  <patternset>
    <include name="**/*.jar"/>
  </patternset>
  <sizeselect size="4" units="Ki" when="more"/>
</fileset>

Selects all JAR files that are larger than 4096 bytes.

Selector Containers

To create more complex selections, a variety of selectors that contain other selectors are available for your use. They combine the selections of their child selectors in various ways.

The selector containers are:

• <and> - select a file only if all the contained selectors select it.
• <majority> - select a file if a majority of its selectors select it.
• <none> - select a file only if none of the contained selectors select it.
• <not> - can contain only one selector, and reverses what it selects and doesn't select.
• <or> - selects a file if any one of the contained selectors selects it.
• <select> - contains only one selector and forwards all requests to it without alteration. This is the selector to use if you want to define a reference. It is usable as an element of <project>.

All selector containers can contain any other selector, including other containers, as an element. Using containers, the selector tags can be arbitrarily deep. Here is a complete list of allowable selector elements within a container:

• <and>
• <containsselect>
• <dateselect>
• <dependselect>
• <depthselect>
• <extendselect>
• <filenameselect>
• <majority>
• <none>
• <not>
• <or>
• <presentselect>
• <select>
• <sizeselect>

And Selector

The <and> tag selects files that are selected by all of the elements it contains. It returns as soon as it finds a selector that does not select the file, so it is not guaranteed to check every selector.

Here is an example of how to use the And Selector:

<fileset dir="${dist}" includes="**/*.jar">
    <and>
        <sizeselect size="4" units="Ki" when="more"/>
        <dateselect datetime="01/01/2001 12:00 AM" when="before"/>
    </and>
</fileset>

Selects all the JAR file larger than 4096 bytes which haven't been update since the last millenium.

Majority Selector

The <majority> tag selects files provided that a majority of the contained elements also select it. Ties are dealt with as specified by the allowtie attribute.

Here is an example of how to use the Majority Selector:

<fileset dir="${docs}" includes="**/*.html">
    <majority>
        <containsselect contains="project" casesensitive="false"/>
        <containsselect contains="taskdef" casesensitive="false"/>
        <containsselect contains="IntrospectionHelper" casesensitive="true"/>
    </majority>
</fileset>

Selects all the HTML files which contain at least two of the three phrases "project", "taskdef", and "IntrospectionHelper" (this last phrase must match case exactly).

None Selector

The <none> tag selects files that are not selected by any of the elements it contains. It returns as soon as it finds a selector that selects the file, so it is not guaranteed to check every selector.

Here is an example of how to use the None Selector:

<fileset dir="${src}" includes="**/*.java">
    <none>
        <presentselect targetdir="${dest}"/>
        <presentselect targetdir="${dest}">
            <mapper type="glob" from="*.java" to="*.class"/>
        </presentselect>
    </none>
</fileset>

Selects only Java files which do not have equivalent java or class files in the dest directory.

Not Selector

The <not> tag reverses the meaning of the single selector it contains.

Here is an example of how to use the Not Selector:

<fileset dir="${src}" includes="**/*.java">
    <not>
        <containsselect contains="test"/>
    </not>
</fileset>

Selects all the files in the src directory that do not contain the string "test".

Or Selector

The <or> tag selects files that are selected by any one of the elements it contains. It returns as soon as it finds a selector that selects the file, so it is not guaranteed to check every selector.

Here is an example of how to use the Or Selector:

<fileset dir="${basedir}">
    <or>
        <depthselect max="0"/>
        <filenameselect name="*.png"/>
        <filenameselect name="*.gif"/>
        <filenameselect name="*.jpg"/>
    </or>
</fileset>

Selects all the files in the top directory along with all the image files below it.

Select Selector

The <select> tag is used to create selectors that can be reused through references. It should be used outside of any target, as an element of the <project> tag. It can contain only one other selector, but of course that selector can be a container.

Here is an example of how to use the Select Selector:

<project default="all" basedir="./jakarta-ant">

    <select id="completed">
        
            <dependselect targetdir="build/classes">
                <mapper type="glob" from="*.java" to="*.class"/>
            </dependselect>
            <dependselect targetdir="docs/manual/api">
                <mapper type="glob" from="*.java" to="*.html"/>
            </dependselect>
        
    </select>

    <target>
        <zip>
            <fileset dir="src/main" includes="**/*.java">
                <select refid="completed"/>
            </fileset>
        </zip>
    </target>
    
</project>

Selects all the Java files which have an up-to-date equivalent class file and javadoc file associated with them.

Extend Selectors

You can write your own selectors and use them within the selector containers by specifying them within the <extendselect> tag.

First, you have to write your selector class in Java. The only requirement it must meet in order to be a selector is that it implements the org.apache.tools.ant.types.selectors.FileSelector interface, which contains a single method. See Programming Selectors in Ant for more information.

Once they are written, you include them in your build file by using the <extendselect> tag.

Here is how you use <extendselect> to use your class as a selector:

<fileset dir="${mydir}" includes="**/*">
    <extendselect classname="com.mydomain.MySelector">
        <param name="myattribute" value="myvalue"/>
    </extendselect>
</fileset>

A number of static selectors can also be used as extend selectors by specifying their attributes using <param> elements. These are

• Contains Selector
• Date Selector
• Depth Selector
• Filename Selector
• Size Selector

For more details concerning writing your own selectors, consult Programming Selectors in Ant.