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.

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 AM_or_PM, 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.
Since Ant 1.6.2

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.

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:

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.

If a file is only present in targetdir (or after applying the
mapper) it is ignored.

Files with different lengths are different.

If ignoreFileTimes is turned off, then differing file
timestamps will cause files to be regarded as different.

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.

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

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:

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:

get the absolute path for the file

get the cached value from the configured cache (absolute path as key)

get the new value from the configured algorithm

compare these two values with the configured comparator

update the cache if needed and requested

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.

Attribute

Description

Required

algorithm

The type of algorithm should be used.
Acceptable values are (further information see later):

hashvalue - HashvalueAlgorithm

digest - DigestAlgorithm

checksum - ChecksumAlgorithm

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

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 : 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 transferred to the cache via its
setXX-methods

comparator.* : Value is transferred to the comparator via its
setXX-methods

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:

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.

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

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.

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.

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

<selector> - contains only one
selector and forwards all requests to it without alteration, provided
that any "if" or
"unless" conditions are met. This
is the selector to use if you want to define a reference. It is
usable as an element of <project>. It is also
the one to use if you want selection of files to be dependent on
Ant property settings.

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:

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.

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

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.