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> - Select files that contain a particular text string
• <date> - Select files that have been modified either before or after a particular date and time
• <depend> - Select files that have been modified more recently than equivalent files elsewhere
• <depth> - Select files that appear so many directories down in a directory tree
• <different> - Select files that are different from those elsewhere
• <filename> - Select files whose name matches a particular pattern. Equivalent to the include and exclude elements of a patternset.
• <present> - Select files that either do or do not exist in some other location
• <containsregexp> - Select files that match a regular expression
• <size> - Select files that are larger or smaller than a particular number of bytes.
• <type> - Select files that are either regular files or directories.
• <modified> - Select files if the return value of the configured algorithm is different from that stored in a cache.
• <signedselector> - Select files if they are signed, and optionally if they have a signature of a certain name.
• <scriptselector> - Use a BSF or JSR 223 scripting language to create your own selector
• <readable> - Select files if they are readable.
• <writable> - Select files if they are writable.

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).

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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 : same as attribute algorithm
• cache : same as attribute cache
• comparator : same as attribute comparator
• algorithmclass : same as attribute algorithmclass
• cacheclass : same as attribute cacheclass
• comparatorclass : same as attribute comparatorclass
• update : same as attribute update
• seldirs : same as attribute seldirs
• algorithm.* : Value is transferred to the algorithm via its setXX-methods
• cache.* : Value is transfered to the cache via its setXX-methods
• comparator.* : Value is transfered to the comparator via its setXX-methods

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.

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 sele