Selectors

The IzPack selector for the FileSet concept has been adapted from the Apache Ant Selector core type. The functionality has been reduced to the satisfy the needs of IzPack.

Selectors are a mechanism whereby the files that make up a fileset can be selected using more criteria than the file name 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 used as a reference.

Different selectors have different attributes. Some selectors can contain other selectors, and these are called Selector Containers.

Core Selectors

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

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.

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 far down they are stored in the directory structure 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>tag selects files who are deemed to be 'different' from another, equivalent file in another location. The rules for determining difference between two files are as follows:

1. If there is no 'other' file, it's different.
2. Files with different lengths are different.
3. If ignoreFileTimesis turned off, then differing file timestamps will cause files to be regarded as different.
4. 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 the preservelastmodified to propagate the timestamp from source file to destination file.

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

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 contain a match to the regular expression specified by the expression attribute.

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 can be 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>

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.

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>
• <contains>
• <custom>
• <date>
• <depend>
• <depth>
• <filename>
• <majority>
• <none>
• <not>
• <or>
• <present>
• <size>

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

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.

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