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 <selector> 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 Custom Selectors. The ones built in to Apache Ant are called Core Selectors.

Core Selectors

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

The core selectors are:

Contains Selector

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

The <contains> selector can be used as a ResourceSelector (see the <restrict> ResourceCollection).

Attribute Description Required
text Specifies the text that every file must contain Yes
casesensitive Whether to pay attention to case when looking for the string in the text attribute. Default is true. No
ignorewhitespace Whether to eliminate whitespace before checking for the string in the text attribute. Default is false. No
encoding Encoding of the resources being selected. Required in practice if the encoding of the files being selected is different from the default encoding of the JVM where Ant is running. Since Ant 1.9.0 No

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

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

Selects all the HTML files that contain the string script.

Date Selector

The <date> 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.

Attribute Description Required
datetime Specifies the date and time to test for. Should be in the format "MM/dd/yyyy hh:mm a" using the US locale, or an alternative pattern specified via the pattern attribute. At least one of the two.
millis The number of milliseconds since 1970 that should be tested for. It is usually much easier to use the datetime attribute.
when Indicates how to interpret the date, whether the files to be selected are those whose last modified times should be before, after, or equal to the specified value. Acceptable values for this attribute are:
  • before - select files whose last modified date is before the indicated date
  • after - select files whose last modified date is after the indicated date
  • equal - select files whose last modified date is this exact date
The default is equal. 		No
granularity The number of milliseconds leeway to use when comparing file modification times. This is needed because not every file system supports tracking the last modified time to the millisecond level. Default is 0 milliseconds, or 2 seconds on DOS systems. No
pattern The SimpleDateFormat-compatible pattern to use when interpreting the datetime attribute using the current locale. Since Ant 1.6.2 No
checkdirs Indicates whether or not to check dates on directories. No, defaults to false

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

<fileset dir="${jar.path}" includes="**/*.jar">
    <date 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 <depend> tag selects files whose last modified date is later than another, equivalent file in another location.

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

The <depend> selector is case-sensitive.

Attribute Description Required
targetdir The base directory to look for the files to compare against. The precise location depends on a combination of this attribute and the <mapper> element, if any. Yes
granularity The number of milliseconds leeway to give before deciding a file is out of date. This is needed because not every file system supports tracking the last modified time to the millisecond level. Default is 0 milliseconds, or 2 seconds on DOS systems. No

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

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <depend 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 <depth> tag selects files based on how many directory levels deep they are in relation to the base directory of the fileset.

Attribute Description Required
min The minimum number of directory levels below the base directory that a file must be in order to be selected. Default is no limit. At least one of the two.
max The maximum number of directory levels below the base directory that a file can be and still be selected. Default is no limit.

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

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

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

Different Selector

The <different> selector will select a file if it is deemed to be 'different' from an equivalent file in another location. The rules for determining difference between the two files are as follows:

  1. If a file is only present in the resource collection you apply the selector to but not in targetdir (or after applying the mapper) the file is selected.
  2. If a file is only present in targetdir (or after applying the mapper) it is ignored.
  3. Files with different lengths are different.
  4. If ignoreFileTimes is turned off, then differing file timestamps will cause files to be regarded as different.
  5. Unless ignoreContents is set to true, a byte-for-byte check is run against the two files.
This is a useful selector to work with programs and tasks that don't handle dependency checking properly; even if a predecessor task always creates its output files, followup tasks can be driven off copies made with a different selector, so their dependencies are driven on the absolute state of the files, not just a timestamp. For example: anything fetched from a web site, or the output of some program. To reduce the amount of checking, when using this task inside a <copy> task, set preservelastmodified to true to propagate the timestamp from the source file to the destination file.

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

Attribute Description Required
targetdir The base directory to look for the files to compare against. The precise location depends on a combination of this attribute and the <mapper> element, if any. Yes
ignoreFileTimes Whether to use file times in the comparison or not. Default is true (time differences are ignored). No
ignoreContents Whether to do a byte per byte compare. Default is false (contents are compared). Since Ant 1.6.3 No
granularity The number of milliseconds leeway to give before deciding a file is out of date. This is needed because not every file system supports tracking the last modified time to the millisecond level. Default is 0 milliseconds, or 2 seconds on DOS systems. No

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

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

Compares all the Java source files between the 1.4.1 and the 1.5 release and selects those who are different, disregarding file times.

Filename Selector

The <filename> 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.

The <filename> selector is case-sensitive.

Attribute Description Required
name The name of files to select. The name parameter can contain the standard Ant wildcard characters. Exactly one of the two
regex The regular expression matching files to select.
casesensitive Whether to pay attention to case when looking at file names. Default is "true". No
negate Whether to reverse the effects of this filename selection, therefore emulating an exclude rather than include tag. Default is "false". No

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

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

Selects all the cascading style sheet files.

Present Selector

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

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

The <present> selector is case-sensitive.

Attribute Description Required
targetdir The base directory to look for the files to compare against. The precise location depends on a combination of this attribute and the <mapper> element, if any. Yes
present Whether we are requiring that a file is present in the src directory tree only, or in both the src and the target directory tree. Valid values are:
  • srconly - select files only if they are in the src directory tree but not in the target directory tree
  • both - select files only if they are present both in the src and target directory trees
Default is both. Setting this attribute to "srconly" is equivalent to wrapping the selector in the <not> selector container. 		No

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

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

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

Regular Expression Selector

The <containsregexp> tag in a FileSet limits the files defined by that fileset to only those which contents contain a match to the regular expression specified by the expression attribute.

The <containsregexp> selector can be used as a ResourceSelector (see the <restrict> ResourceCollection).

Attribute Description Required
expression Specifies the regular expression that must match true in every file Yes
casesensitive Perform a case sensitive match. Default is true. since Ant 1.8.2 No
multiline Perform a multi line match. Default is false. since Ant 1.8.2 No
singleline This allows '.' to match new lines. SingleLine is not to be confused with multiline, SingleLine is a perl regex term, it corresponds to dotall in java regex. Default is false. since Ant 1.8.2 No

Here is an example of how to use the regular expression Selector:

<fileset dir="${doc.path}" includes="*.txt">
    <containsregexp expression="[4-6]\.[0-9]"/>
</fileset>

Selects all the text files that match the regular expression (have a 4,5 or 6 followed by a period and a number from 0 to 9).

Size Selector

The <size> 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.

Attribute Description Required
value The size of the file which should be tested for. Yes
units The units that the value attribute is expressed in. When using the standard single letter SI designations, such as "k","M", or "G", multiples of 1000 are used. If you want to use power of 2 units, use the IEC standard: "Ki" for 1024, "Mi" for 1048576, and so on. The default is no units, which means the value attribute expresses the exact number of bytes. No
when Indicates how to interpret the size, whether the files to be selected should be larger, smaller, or equal to that value. Acceptable values for this attribute are:
  • less - select files less than the indicated size
  • more - select files greater than the indicated size
  • equal - select files this exact size
The default is equal. 		No

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

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

Selects all JAR files that are larger than 4096 bytes.

Type Selector

The <type> tag selects files of a certain type: directory or regular.

Attribute Description Required
type The type of file which should be tested for. Acceptable values are:
  • file - regular files
  • dir - directories
 Yes

Here is an example of how to use the Type Selector to select only directories in ${src}

<fileset dir="${src}">
  <type type="dir"/>
</fileset>

The Type Selector is often used in conjunction with other selectors. For example, to select files that also exist in a template directory, but avoid selecting empty directories, use: 

<fileset dir="${src}">
    <and>
        <present targetdir="template"/>
        <type type="file"/>
    </and>
</fileset>

Modified Selector

The <modified> selector computes a value for a file, compares that to the value stored in a cache and select the file, if these two values differ.

Because this selector is highly configurable the order in which the selection is done is:

  1. get the absolute path for the file
  2. get the cached value from the configured cache (absolute path as key)
  3. get the new value from the configured algorithm
  4. compare these two values with the configured comparator
  5. update the cache if needed and requested
  6. do the selection according to the comparison result

The comparison, computing of the hashvalue and the store is done by implementation of special interfaces. Therefore they may provide additional parameters.

The <modified> selector can be used as a ResourceSelector (see the <restrict> ResourceCollection). In that case it maps simple file resources to files and does its job. If the resource is from another type, the <modified> selector tries to (attention!) copy the content into a local file for computing the hashvalue.

If the source resource is not a filesystem resource the modified selector will download it to the temporary directory.

Attribute Description Required
algorithm The type of algorithm should be used. Acceptable values are (further information see later):
  • hashvalue - HashvalueAlgorithm
  • digest - DigestAlgorithm
  • checksum - ChecksumAlgorithm
  • lastmodified - LastModifiedAlgorithm
No, defaults to digest
cache The type of cache should be used. Acceptable values are (further information see later):
  • propertyfile - PropertyfileCache
No, defaults to propertyfile
comparator The type of comparator should be used. Acceptable values are (further information see later):
  • equal - EqualComparator
  • rule - java.text.RuleBasedCollator (see note for restrictions)
No, defaults to equal
algorithmclass Classname of custom algorithm implementation. Lower priority than algorithm. No
cacheclass Classname of custom cache implementation. Lower priority than cache. No
comparatorclass Classname of custom comparator implementation. Lower priority than comparator. No
update Should the cache be updated when values differ? (boolean) No, defaults to true
seldirs Should directories be selected? (boolean) No, defaults to true
selres Should Resources without an InputStream, and therefore without checking, be selected? (boolean) No, defaults to true. Only relevant when used as ResourceSelector.
delayupdate If set to true, the storage of the cache will be delayed until the next finished BuildEvent; task finished, target finished or build finished, whichever comes first. This is provided for increased performance. If set to false, the storage of the cache will happen with each change. This attribute depends upon the update attribute. (boolean) No, defaults to true

These attributes can be set with nested <param/> tags. With <param/> tags you can set other values too - as long as they are named according to the following rules:

Algorithm options
Name Description
hashvalue Reads the content of a file into a java.lang.String and use thats hashValue(). No additional configuration required.
digest Uses java.security.MessageDigest. This Algorithm supports the following attributes:
  • algorithm.algorithm (optional): Name of the Digest algorithm (e.g. 'MD5' or 'SHA', default = MD5)
  • algorithm.provider (optional): Name of the Digest provider (default = null)
checksum Uses java.util.zip.Checksum. This Algorithm supports the following attributes:
  • algorithm.algorithm (optional): Name of the algorithm (e.g. 'CRC' or 'ADLER', default = CRC)
lastmodified Uses the lastModified property of a file. No additional configuration is required.
Cache options
propertyfile Use the java.util.Properties class and its possibility to load and store to file. This Cache implementation supports the following attributes:
  • cache.cachefile (optional): Name of the properties-file (default = cache.properties)
Comparator options
equal Very simple object comparison.
rule Uses java.text.RuleBasedCollator for Object comparison. (see note for restrictions)

The <modified> selector supports a nested <classpath> element that represents a PATH like structure for finding custom interface implementations.

Here are some examples of how to use the Modified Selector:

    <copy todir="dest">
        <fileset dir="src">
            <modified/>
        </fileset>
    </copy>

This will copy all files from src to dest which content has changed. Using an updating PropertyfileCache with cache.properties and MD5-DigestAlgorithm.

    <copy todir="dest">
        <fileset dir="src">
            <modified update="true"
                      seldirs="true"
                      cache="propertyfile"
                      algorithm="digest"
                      comparator="equal">
                <param name="cache.cachefile"     value="cache.properties"/>
                <param name="algorithm.algorithm" value="MD5"/>
            </modified>
        </fileset>
    </copy>

This is the same example rewritten as CoreSelector with setting the all the values (same as defaults are).

    <copy todir="dest">
        <fileset dir="src">
            <custom class="org.apache.tools.ant.types.selectors.modifiedselector.ModifiedSelector">
                <param name="update"     value="true"/>
                <param name="seldirs"    value="true"/>
                <param name="cache"      value="propertyfile"/>
                <param name="algorithm"  value="digest"/>
                <param name="comparator" value="equal"/>
                <param name="cache.cachefile"     value="cache.properties"/>
                <param name="algorithm.algorithm" value="MD5"/>
            </custom>
        </fileset>
    </copy>

And this is the same rewritten as CustomSelector.

  <target name="generate-and-upload-site">
      <echo> generate the site using forrest </echo>
      <antcall target="site"/>

      <echo> upload the changed file </echo>
      <ftp server="${ftp.server}" userid="${ftp.user}" password="${ftp.pwd}">
          <fileset dir="htdocs/manual">
              <modified/>
          </fileset>
      </ftp>
  </target>

A useful scenario for this selector inside a build environment for homepage generation (e.g. with Apache Forrest). Here all changed files are uploaded to the server. The CacheSelector saves therefore much upload time.

  <modified cacheclassname="com.mycompany.MyCache">
      <classpath>
          <pathelement location="lib/mycompany-antutil.jar"/>
      </classpath>
  </modified>

Uses com.mycompany.MyCache from a jar outside of Ants own classpath as cache implementation

Note on RuleBasedCollator

The RuleBasedCollator needs a format for its work, but its needed while instantiation. There is a problem in the initialization algorithm for this case. Therefore you should not use this (or tell me the workaround :-).

Signed Selector

The <signedselector> tag selects signed files and optionally signed with a certain name.

This selector has been added in Apache Ant 1.7.

Attribute Description Required
name The signature name to check for. no

Readable Selector

The <readable> selector selects only files that are readable. Ant only invokes java.io.File#canRead so if a file is unreadable but the Java VM cannot detect this state, this selector will still select the file.

Writable Selector

The <writable> selector selects only files that are writable. Ant only invokes java.io.File#canWrite so if a file is unwritable but the Java VM cannot detect this state, this selector will still select the file.

Script Selector

The <scriptselector> element enables you to write a complex selection algorithm in any Apache BSF or JSR 223 supported language. See the Script task for an explanation of scripts and dependencies.

This selector was added in Apache Ant 1.7.

Attribute Description Required
language language of the script. yes
manager The script engine manager to use. See the script task for using this attribute. No - default is "auto"
src filename of the script no
setbeans whether to have all properties, references and targets as global variables in the script. No, default is "true".
classpath The classpath to pass into the script. No
classpathref The classpath to use, given as a reference to a path defined elsewhere. No

This selector can take a nested <classpath> element. See the script task on how to use this element.

If no src attribute is supplied, the script must be nested inside the selector declaration.

The embedded script is invoked for every test, with the bean self is bound to the selector. It has an attribute selected must can be set using setSelected(boolean) to select that file.

The following beans are configured for every script, alongside the classic set of project, properties, and targets.
Bean Description Type
self selector instance org.apache.tools.ant.types.optional
filename filename of the selection String
file file of the selection java.io.File
basedir Fileset base directory java.io.File

The self bean maps to the selector, which has the following attributes. Only the selected flag is writable, the rest are read only via their getter methods.
Attribute Description Type
selected writeable flag to select this file boolean
filename filename of the selection String
file file of the selection java.io.File
basedir Fileset base directory java.io.File

Example 

    <scriptselector language="javascript">
      self.setSelected(true);
    </scriptselector>

Selects every file. 

    <scriptselector language="javascript">
      self.setSelected((filename.length%2)==0);
    </scriptselector>
Select files whose filename length is even.

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:

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 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>
        <size value="4" units="Ki" when="more"/>
        <date 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 millennium.

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.

Attribute Description Required
allowtie Whether files should be selected if there are an even number of selectors selecting them as are not selecting them. Default is true. No

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

<fileset dir="${docs}" includes="**/*.html">
    <majority>
        <contains text="project" casesensitive="false"/>
        <contains text="taskdef" casesensitive="false"/>
        <contains text="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>
        <present targetdir="${dest}"/>
        <present targetdir="${dest}">
            <mapper type="glob" from="*.java" to="*.class"/>
        </present>
    </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>
        <contains text="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>
        <depth max="0"/>
        <filename name="*.png"/>
        <filename name="*.gif"/>
        <filename name="*.jpg"/>
    </or>
</fileset>

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

Selector Reference

The <selector> tag is used to create selectors that can be reused through references. It is the only selector which can 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.

The <selector> tag can also be used to select files conditionally based on whether an Ant property exists or not. This functionality is realized using the "if" and "unless" attributes in exactly the same way they are used on targets or on the <include> and <exclude> tags within a <patternset>.

Attribute Description Required
if Allow files to be selected only if the named property is set. No
unless Allow files to be selected only if the named property is not set. No

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

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

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

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

</project>

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

And an example of selecting files conditionally, based on whether properties are set:

<fileset dir="${working.copy}">
    <or>
        <selector if="include.tests">
            <filename name="**/*Test.class">
        </selector>
        <selector if="include.source">
            <and>
                <filename name="**/*.java">
                <not>
                    <selector unless="include.tests">
                        <filename name="**/*Test.java">
                    </selector>
                </not>
            </and>
        </selector>
    </or>
</fileset>

A fileset that conditionally contains Java source files and Test source and class files.

Custom Selectors

You can write your own selectors and use them within the selector containers by specifying them within the <custom> 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 that is written, you include it in your build file by using the <custom> tag.

Attribute Description Required
classname The name of your class that implements org.apache.tools.ant.types.selectors.FileSelector. Yes
classpath The classpath to use in order to load the custom selector class. If neither this classpath nor the classpathref are specified, the class will be loaded from the classpath that Ant uses. No
classpathref A reference to a classpath previously defined. If neither this reference nor the classpath above are specified, the class will be loaded from the classpath that Ant uses. No

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

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

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

Here is the example from the Depth Selector section rewritten to use the selector through <custom>.

<fileset dir="${doc.path}" includes="**/*">
    <custom classname="org.apache.tools.ant.types.selectors.DepthSelector">
        <param name="max" value="1"/>
    </custom>
</fileset>

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

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