| <html> |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Selectors in Ant</title> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css"> |
| </head> |
| |
| <body> |
| <h2>Selectors</h2> |
| |
| <p>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 <code><include></code> and <code><exclude></code> |
| tags.</p> |
| |
| <h3>How to use a Selector</h3> |
| |
| <p>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. |
| </p> |
| |
| <p>Different selectors have different attributes. Some selectors can |
| contain other selectors, and these are called |
| <a href="#selectcontainers"><code>Selector Containers</code></a>. |
| There is also a category of selectors that allow |
| user-defined extensions, called |
| <a href="#customselect"><code>Custom Selectors</code></a>. |
| The ones built in to Ant are called |
| <a href="#coreselect"><code>Core Selectors</code></a>. |
| </p> |
| |
| <a name="coreselect"></a> |
| <h3>Core Selectors</h3> |
| |
| <p>Core selectors are the ones that come standard |
| with Ant. They can be used within a fileset and can be contained |
| within Selector Containers.</p> |
| |
| <p>The core selectors are:</p> |
| |
| <ul> |
| <li><a href="#containsselect"><contains></a> - Select |
| files that contain a particular text string</li> |
| <li><a href="#dateselect"><date></a> - Select files |
| that have been modified either before or after a particular date |
| and time</li> |
| <li><a href="#dependselect"><depend></a> - Select files |
| that have been modified more recently than equivalent files |
| elsewhere</li> |
| <li><a href="#depthselect"><depth></a> - Select files |
| that appear so many directories down in a directory tree</li> |
| <li><a href="#differentselect"><different></a> - Select files |
| that are different from those elsewhere</li> |
| <li><a href="#filenameselect"><filename></a> - Select |
| files whose name matches a particular pattern. Equivalent to |
| the include and exclude elements of a patternset.</li> |
| <li><a href="#presentselect"><present></a> - Select |
| files that either do or do not exist in some other location</li> |
| <li><a href="#regexpselect"><containsregexp></a> - Select |
| files that match a regular expression</li> |
| <li><a href="#sizeselect"><size></a> - Select files |
| that are larger or smaller than a particular number of bytes.</li> |
| <li><a href="#typeselect"><type></a> - Select files |
| that are either regular files or directories.</li> |
| <li><a href="#modified"><modified></a> - Select files if |
| the return value of the configured algorithm is different from that |
| stored in a cache.</li> |
| </ul> |
| |
| <a name="containsselect"></a> |
| <h4>Contains Selector</h4> |
| |
| <p>The <code><contains></code> tag in a FileSet limits |
| the files defined by that fileset to only those which contain the |
| string specified by the <code>text</code> attribute. |
| .</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">text</td> |
| <td valign="top">Specifies the text that every file must contain |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">casesensitive</td> |
| <td valign="top">Whether to pay attention to case when looking |
| for the string in the <code>text</code> attribute. Default is |
| true. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">ignorewhitespace</td> |
| <td valign="top">Whether to eliminate whitespace before checking |
| for the string in the <code>text</code> attribute. Default is |
| false. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the Contains Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${doc.path}" includes="**/*.html"> |
| <contains text="script" casesensitive="no"/> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects all the HTML files that contain the string |
| <code>script</code>.</p> |
| |
| |
| <a name="dateselect"></a> |
| <h4>Date Selector</h4> |
| |
| <p>The <code><date></code> 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.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">datetime</td> |
| <td valign="top">Specifies the date and time to test for using |
| a string of the format MM/DD/YYYY HH:MM AM_or_PM. |
| </td> |
| <td valign="top" align="center" rowspan="2">At least one of the two.</td> |
| </tr> |
| <tr> |
| <td valign="top">millis</td> |
| <td valign="top">The number of milliseconds since 1970 that should |
| be tested for. It is usually much easier to use the datetime |
| attribute. |
| </td> |
| </tr> |
| <tr> |
| <td valign="top">when</td> |
| <td valign="top">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: |
| <ul> |
| <li>before - select files whose last modified date is before the indicated date |
| <li>after - select files whose last modified date is after the indicated date |
| <li>equal - select files whose last modified date is this exact date |
| </ul> |
| The default is equal. |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the Date Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${jar.path}" includes="**/*.jar"> |
| <date datetime="01/01/2001 12:00 AM" when="before"/> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects all JAR files which were last modified before midnight |
| January 1, 2001.</p> |
| |
| |
| <a name="dependselect"></a> |
| <h4>Depend Selector</h4> |
| |
| <p>The <code><depend></code> tag selects files |
| whose last modified date is later than another, equivalent file in |
| another location.</p> |
| |
| <p>The <code><depend></code> tag supports the use of a |
| contained <a href="mapper.html"><code><mapper></code></a> element |
| to define the location of the file to be compared against. If no |
| <code><mapper></code> element is specified, the |
| <code>identity</code> type mapper is used.</p> |
| |
| <p>The <code><depend></code> selector is case-sensitive.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">targetdir</td> |
| <td valign="top">The base directory to look for the files to compare |
| against. The precise location depends on a combination of this |
| attribute and the <code><mapper></code> element, if any. |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">granularity</td> |
| <td valign="top">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. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the Depend Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${ant.1.5}/src/main" includes="**/*.java"> |
| <depend targetdir="${ant.1.4.1}/src/main"/> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects all the Java source files which were modified in the |
| 1.5 release. |
| </p> |
| |
| |
| <a name="depthselect"></a> |
| <h4>Depth Selector</h4> |
| |
| <p>The <code><depth></code> tag selects files based on |
| how many directy levels deep they are in relation to the base |
| directory of the fileset. |
| </p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">min</td> |
| <td valign="top">The minimum number of directory levels below |
| the base directory that a file must be in order to be selected. |
| Default is no limit. |
| </td> |
| <td valign="top" align="center" rowspan="2">At least one of the two.</td> |
| </tr> |
| <tr> |
| <td valign="top">max</td> |
| <td valign="top">The maximum number of directory levels below |
| the base directory that a file can be and still be selected. |
| Default is no limit. |
| </td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the Depth Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${doc.path}" includes="**/*"> |
| <depth max="1"/> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects all files in the base directory and one directory below |
| that.</p> |
| |
| <a name="differentselect"> |
| <h4>Different Selector</h4> |
| |
| <p>The <code><different></code> 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: |
| <ol> |
| <li> If there is no 'other' file, it's different. |
| <li> Files with different lengths are different. |
| <li> If <tt>ignoreFileTimes</tt> is turned off, then differing file |
| timestamps will cause files to be regarded as different. |
| <li> Finally a byte-for-byte check is run against the two files |
| </ol> |
| |
| 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 <tt>preservelastmodified</tt> to propagate the timestamp |
| from source file to destintaion file. |
| |
| |
| <p> |
| |
| The <code><different></code> tag supports the use of a |
| contained <a href="mapper.html"><code><mapper></code></a> element |
| to define the location of the file to be compared against. If no |
| <code><mapper></code> element is specified, the |
| <code>identity</code> type mapper is used.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">targetdir</td> |
| <td valign="top">The base directory to look for the files to compare |
| against. The precise location depends on a combination of this |
| attribute and the <code><mapper></code> element, if any. |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">ignoreFileTimes</td> |
| <td valign="top">Whether to use file times in the comparison or not. |
| Default is true (time differences are ignored). |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">granularity</td> |
| <td valign="top">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. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the Different Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${ant.1.5}/src/main" includes="**/*.java"> |
| <different targetdir="${ant.1.4.1}/src/main" |
| ignoreFileTimes="true"/> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>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. |
| </p> |
| |
| <a name="filenameselect"></a> |
| <h4>Filename Selector</h4> |
| |
| <p>The <code><filename></code> tag acts like the |
| <code><include></code> and <code><exclude></code> |
| tags within a fileset. By using a selector instead, however, |
| one can combine it with all the other selectors using whatever |
| <a href="#selectcontainers">selector container</a> is desired. |
| </p> |
| |
| <p>The <code><filename></code> selector is |
| case-sensitive.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">name</td> |
| <td valign="top">The name of files to select. The name parameter |
| can contain the standard Ant wildcard characters. |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">casesensitive</td> |
| <td valign="top">Whether to pay attention to case when looking |
| at file names. Default is "true". |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">negate</td> |
| <td valign="top">Whether to reverse the effects of this filename |
| selection, therefore emulating an exclude rather than include |
| tag. Default is "false". |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the Filename Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${doc.path}" includes="**/*"> |
| <filename name="**/*.css"/> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects all the cascading style sheet files.</p> |
| |
| |
| <a name="presentselect"></a> |
| <h4>Present Selector</h4> |
| |
| <p>The <code><present></code> tag selects files |
| that have an equivalent file in another directory tree.</p> |
| |
| <p>The <code><present></code> tag supports the use of a |
| contained <a href="mapper.html"><code><mapper></code></a> element |
| to define the location of the file to be tested against. If no |
| <code><mapper></code> element is specified, the |
| <code>identity</code> type mapper is used.</p> |
| |
| <p>The <code><present></code> selector is case-sensitive.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">targetdir</td> |
| <td valign="top">The base directory to look for the files to compare |
| against. The precise location depends on a combination of this |
| attribute and the <code><mapper></code> element, if any. |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">present</td> |
| <td valign="top">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: |
| <ul> |
| <li>srconly - select files only if they are in the src |
| directory tree but not in the target directory tree |
| <li>both - select files only if they are present both in the |
| src and target directory trees |
| </ul> |
| Default is both. Setting this attribute to "srconly" |
| is equivalent to wrapping the selector in the <not> |
| selector container. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the Present Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${ant.1.5}/src/main" includes="**/*.java"> |
| <present present="srconly" targetdir="${ant.1.4.1}/src/main"/> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects all the Java source files which are new in the |
| 1.5 release. |
| </p> |
| |
| <a name="regexpselect"></a> |
| <h4>Regular Expression Selector</h4> |
| |
| <p>The <code><containsregexp></code> 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 <code>expression</code> attribute. |
| </p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">expression</td> |
| <td valign="top">Specifies the regular expression that must |
| match true in every file</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the regular expression Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${doc.path}" includes="*.txt"> |
| <containsregexp expression="[4-6]\.[0-9]"/> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>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). |
| |
| |
| <a name="sizeselect"></a> |
| <h4>Size Selector</h4> |
| |
| <p>The <code><size></code> 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.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">value</td> |
| <td valign="top">The size of the file which should be tested for. |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">units</td> |
| <td valign="top">The units that the <code>value</code> 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 <code>value</code> attribute expresses the exact |
| number of bytes. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">when</td> |
| <td valign="top">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: |
| <ul> |
| <li>less - select files less than the indicated size |
| <li>more - select files greater than the indicated size |
| <li>equal - select files this exact size |
| </ul> |
| The default is less. |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the Size Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${jar.path}"> |
| <patternset> |
| <include name="**/*.jar"/> |
| </patternset> |
| <size value="4" units="Ki" when="more"/> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects all JAR files that are larger than 4096 bytes.</p> |
| |
| <a name="typeselect"></a> |
| <h4>Type Selector</h4> |
| |
| <p>The <code><type></code> tag selects files of a certain type: |
| directory or regular.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">type</td> |
| <td valign="top">The type of file which should be tested for. |
| Acceptable values are: |
| <ul> |
| <li>file - regular files</li> |
| <li>dir - directories</li> |
| </ul> |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the Type Selector to select only |
| directories in <code>${src}</code></p> |
| |
| <blockquote><pre> |
| <fileset dir="${src}"> |
| <type type="dir"/> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>The Type Selector is often used in conjunction with other selectors. |
| For example, to select files that also exist in a <code>template</code> |
| directory, but avoid selecting empty directories, use: |
| |
| <blockquote><pre> |
| <fileset dir="${src}"> |
| <and> |
| <present targetdir="template"/> |
| <type type="file"/> |
| </and> |
| </fileset> |
| </pre></blockquote> |
| |
| |
| <a name="modified"></a> |
| <h4>Modified Selector</h4> |
| <p>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.</p> |
| <p>Because this selector is highly configurable the order in which the selection is done |
| is: <ol> |
| <li> get the absolute path for the file </li> |
| <li> get the cached value from the configured cache (absolute path as key) </li> |
| <li> get the new value from the configured algorithm </li> |
| <li> compare these two values with the configured comparator </li> |
| <li> update the cache if needed and requested </li> |
| <li> do the selection according to the comparison result </li> |
| </ol> |
| The comparison, computing of the hashvalue and the store is done by implementation |
| of special interfaces. Therefore they may provide additional parameters.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top"> algorithm </td> |
| <td valign="top"> The type of algorithm should be used. |
| Acceptable values are (further information see later): |
| <ul> |
| <li> hashvalue - HashvalueAlgorithm </li> |
| <li> digest - DigestAlgorithm </li> |
| </ul> |
| </td> |
| <td valign="top" align="center"> No, defaults to <i>digest</i> </td> |
| </tr> |
| <tr> |
| <td valign="top"> cache </td> |
| <td valign="top"> The type of cache should be used. |
| Acceptable values are (further information see later): |
| <ul> |
| <li> propertyfile - PropertyfileCache </li> |
| </ul> |
| </td> |
| <td valign="top" align="center"> No, defaults to <i>propertyfile</i> </td> |
| </tr> |
| <tr> |
| <td valign="top"> comparator </td> |
| <td valign="top"> The type of comparator should be used. |
| Acceptable values are (further information see later): |
| <ul> |
| <li> equal - EqualComparator </li> |
| <li> rule - java.text.RuleBasedCollator </li> |
| </ul> |
| </td> |
| <td valign="top" align="center"> No, defaults to <i>equal</i> </td> |
| </tr> |
| <tr> |
| <td valign="top"> update </td> |
| <td valign="top"> Should the cache be updated when values differ? (boolean) </td> |
| <td valign="top" align="center"> No, defaults to <i>true</i> </td> |
| </tr> |
| <tr> |
| <td valign="top"> seldirs </td> |
| <td valign="top"> Should directories be selected? (boolean) </td> |
| <td valign="top" align="center"> No, defaults to <i>true</i> </td> |
| </tr> |
| </table> |
| |
| <p>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: <ul> |
| <li> <b> algorithm </b>: same as attribute algorithm </li> |
| <li> <b> cache </b>: same as attribute cache </li> |
| <li> <b> comparator </b>: same as attribute cache </li> |
| <li> <b> update </b>: same as attribute comparator </li> |
| <li> <b> seldirs </b>: same as attribute seldirs </li> |
| <li> <b> algorithm.* </b>: Value is transfered to the algorithm via its |
| <i>set</i>XX-methods </li> |
| <li> <b> cache.* </b>: Value is transfered to the cache via its |
| <i>set</i>XX-methods </li> |
| <li> <b> comparator.* </b>: Value is transfered to the comparator via its |
| <i>set</i>XX-methods </li> |
| </ul></p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr><td colspan="2"><font size="+1"><b> Algorithm´s </b></font></td></tr> |
| <tr> |
| <td valign="top"><b>Name</b></td> |
| <td valign="top"><b>Description</b></td> |
| </tr> |
| <tr> |
| <td valign="top"> hashvalue </td> |
| <td valign="top"> Reads the content of a file into a java.lang.String |
| and use thats hashValue(). No additional configuration required. |
| </td> |
| </tr> |
| <tr> |
| <td valign="top"> digest </td> |
| <td valign="top"> Uses java.security.MessageDigest. This Algorithm supports |
| the following attributes: |
| <ul> |
| <li><i>algorithm.algorithm</i> (optional): Name of the Digest algorithm |
| (e.g. 'MD5' or 'SHA', default = <i>MD5</i>) </li> |
| <li><i>algorithm.provider</i> (optional): Name of the Digest provider |
| (default = <i>null</i>) </li> |
| </ul> |
| </td> |
| </tr> |
| <tr><td colspan="2"><font size="+1"><b> Cache´s </b></font></td></tr> |
| <tr> |
| <td valign="top"> propertyfile </td> |
| <td valign="top"> Use the java.util.Properties class and its possibility |
| to load and store to file. |
| This Cache implementation supports the following attributes: |
| <ul> |
| <li><i>cache.cachefile</i> (optional): Name of the properties-file |
| (default = <i>cache.properties</i>) </li> |
| </ul> |
| </td> |
| </tr> |
| <tr><td colspan="2"><font size="+1"><b> Comparator´s </b></font></td></tr> |
| <tr> |
| <td valign="top"> equal </td> |
| <td valign="top"> Very simple object comparison. </td> |
| </tr> |
| <tr> |
| <td valign="top"> rule </td> |
| <td valign="top"> Uses <i>java.text.RuleBasedCollator</i> for Object |
| comparison. |
| </td> |
| </tr> |
| </table> |
| |
| <p>Here are some examples of how to use the Modified Selector:</p> |
| |
| <blockquote><pre> |
| <copy todir="dest"> |
| <fileset dir="src"> |
| <modified/> |
| </fileset> |
| </copy |
| </pre></blockquote> |
| <p>This will copy all files from <i>src</i> to <i>dest</i> which content has changed. |
| Using an updating PropertyfileCache with cache.properties and |
| MD5-DigestAlgorithm.</p> |
| |
| <blockquote><pre> |
| <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> |
| </pre></blockquote> |
| <p>This is the same example rewritten as CoreSelector with setting the all the values |
| (same as defaults are).</p> |
| |
| <blockquote><pre> |
| <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> |
| </pre></blockquote> |
| <p>And this is the same rewritten as CustomSelector.</p> |
| |
| <blockquote><pre> |
| <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> |
| </pre></blockquote> |
| <p>A useful scenario for this selector inside a build environment |
| for homepage generation (e.g. with <a href="http://xml.apache.org/forrest/"> |
| Apache Forrest</a>). Here all <b>changed</b> files are uploaded to the server. The |
| CacheSelector saves therefore much upload time.</p> |
| |
| |
| <a name="selectcontainers"></a> |
| <h3>Selector Containers</h3> |
| |
| <p>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.</p> |
| |
| <p>The selector containers are:</p> |
| |
| <ul> |
| <li><a href="#andselect"><and></a> - select a file only if all |
| the contained selectors select it. |
| <li><a href="#majorityselect"><majority></a> - select a file |
| if a majority of its selectors select it. |
| <li><a href="#noneselect"><none></a> - select a file only if |
| none of the contained selectors select it. |
| <li><a href="#notselect"><not></a> - can contain only one |
| selector, and reverses what it selects and doesn't select. |
| <li><a href="#orselect"><or></a> - selects a file if any one |
| of the contained selectors selects it. |
| <li><a href="#selectorselect"><selector></a> - contains only one |
| selector and forwards all requests to it without alteration, provided |
| that any <code>"if"</code> or |
| <code>"unless"</code> conditions are met. This |
| is the selector to use if you want to define a reference. It is |
| usable as an element of <code><project></code>. It is also |
| the one to use if you want selection of files to be dependent on |
| Ant property settings. |
| </ul> |
| |
| <p>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:</P> |
| |
| <ul> |
| <li><and> |
| <li><contains> |
| <li><custom> |
| <li><date> |
| <li><depend> |
| <li><depth> |
| <li><filename> |
| <li><majority> |
| <li><none> |
| <li><not> |
| <li><or> |
| <li><present> |
| <li><selector> |
| <li><size> |
| </ul> |
| |
| <a name="andselect"></a> |
| <h4>And Selector</h4> |
| |
| <p>The <code><and></code> 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. |
| </p> |
| |
| <p>Here is an example of how to use the And Selector:</p> |
| |
| <blockquote><pre> |
| <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> |
| </pre></blockquote> |
| |
| <p>Selects all the JAR file larger than 4096 bytes which haven't been update |
| since the last millenium. |
| </p> |
| |
| |
| <a name="majorityselect"></a> |
| <h4>Majority Selector</h4> |
| |
| <p>The <code><majority></code> tag selects files provided |
| that a majority of the contained elements also select it. Ties are |
| dealt with as specified by the <code>allowtie</code> attribute. |
| </p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">allowtie</td> |
| <td valign="top">Whether files should be selected if there |
| are an even number of selectors selecting them as are |
| not selecting them. Default is true. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| |
| <p>Here is an example of how to use the Majority Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${docs}" includes="**/*.html"> |
| <majority> |
| <contains text="project" casesensitive="false"/> |
| <contains text="taskdef" casesensitive="false"/> |
| <contains text="IntrospectionHelper" casesensitive="true"/> |
| </majority> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>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). |
| </p> |
| |
| |
| <a name="noneselect"></a> |
| <h4>None Selector</h4> |
| |
| <p>The <code><none></code> 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. |
| </p> |
| |
| <p>Here is an example of how to use the None Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${src}" includes="**/*.java"> |
| <none> |
| <present targetdir="${dest}"/> |
| <present targetdir="${dest}"> |
| <mapper type="glob" from="*.java" to="*.class"/> |
| </present> |
| </none> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects only Java files which do not have equivalent java or |
| class files in the dest directory. |
| </p> |
| |
| |
| <a name="notselect"></a> |
| <h4>Not Selector</h4> |
| |
| <p>The <code><not></code> tag reverses the meaning of the |
| single selector it contains. |
| </p> |
| |
| <p>Here is an example of how to use the Not Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${src}" includes="**/*.java"> |
| <not> |
| <contains text="test"/> |
| </not> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects all the files in the src directory that do not contain the |
| string "test". |
| </p> |
| |
| |
| <a name="orselect"></a> |
| <h4>Or Selector</h4> |
| |
| <p>The <code><or></code> 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. |
| </p> |
| |
| <p>Here is an example of how to use the Or Selector:</p> |
| |
| <blockquote><pre> |
| <fileset dir="${basedir}"> |
| <or> |
| <depth max="0"/> |
| <filename name="*.png"/> |
| <filename name="*.gif"/> |
| <filename name="*.jpg"/> |
| </or> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects all the files in the top directory along with all the |
| image files below it. |
| </p> |
| |
| |
| <a name="selectorselect"></a> |
| <h4>Selector Reference</h4> |
| |
| <p>The <code><selector></code> 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 <code><project></code> tag. It |
| can contain only one other selector, but of course that selector can |
| be a container. |
| </p> |
| |
| <p>The <code><selector></code> tag can also be used to select |
| files conditionally based on whether an Ant property exists or not. |
| This functionality is realized using the <code>"if"</code> and |
| <code>"unless"</code> attributes in exactly the same way they |
| are used on targets or on the <code><include></code> and |
| <code><exclude></code> tags within a |
| <code><patternset></code>.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">if</td> |
| <td valign="top">Allow files to be selected only if the named |
| property is set. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">unless</td> |
| <td valign="top">Allow files to be selected only if the named |
| property is <b>not</b> set. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>Here is an example of how to use the Selector Reference:</p> |
| |
| <blockquote><pre> |
| <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> |
| </pre></blockquote> |
| |
| <p>Zips up all the Java files which have an up-to-date equivalent |
| class file and javadoc file associated with them. |
| </p> |
| |
| <p>And an example of selecting files conditionally, based on whether |
| properties are set:</p> |
| |
| <blockquote><pre> |
| <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> |
| </pre></blockquote> |
| |
| <p>A fileset that conditionally contains Java source files and Test |
| source and class files.</p> |
| |
| <a name="customselect"></a> |
| <h3>Custom Selectors</h3> |
| |
| <p>You can write your own selectors and use them within the selector |
| containers by specifying them within the <custom> tag.</p> |
| |
| <p>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 <code>org.apache.tools.ant.types.selectors.FileSelector</code> |
| interface, which contains a single method. See |
| <a href="selectors-program.html">Programming Selectors in Ant</a> for |
| more information.</p> |
| |
| <p>Once that is written, you include it in your build file by using |
| the <code><custom></code> tag. |
| </p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">classname</td> |
| <td valign="top">The name of your class that implements |
| <code>org.apache.tools.ant.types.selectors.FileSelector</code>. |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">classpath</td> |
| <td valign="top">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. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">classpathref</td> |
| <td valign="top">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. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>Here is how you use <code><custom></code> to |
| use your class as a selector: |
| </p> |
| |
| <blockquote><pre> |
| <fileset dir="${mydir}" includes="**/*"> |
| <custom classname="com.mydomain.MySelector"> |
| <param name="myattribute" value="myvalue"/> |
| </custom> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>A number of core selectors can also be used as custom selectors |
| by specifying their attributes using <param> elements. These |
| are</p> |
| |
| <ul> |
| <li><a href="#containsselect">Contains Selector</a> with |
| classname <code>org.apache.tools.ant.types.selectors.ContainsSelector</code> |
| <li><a href="#dateselect">Date Selector</a> with |
| classname <code>org.apache.tools.ant.types.selectors.DateSelector</code> |
| <li><a href="#depthselect">Depth Selector</a> with |
| classname <code>org.apache.tools.ant.types.selectors.DepthSelector</code> |
| <li><a href="#filenameselect">Filename Selector</a> with |
| classname <code>org.apache.tools.ant.types.selectors.FilenameSelector</code> |
| <li><a href="#sizeselect">Size Selector</a> with |
| classname <code>org.apache.tools.ant.types.selectors.SizeSelector</code> |
| </ul> |
| |
| <p>Here is the example from the Depth Selector section rewritten |
| to use the selector through <code><custom></code>.</p> |
| |
| <blockquote><pre> |
| <fileset dir="${doc.path}" includes="**/*"> |
| <custom classname="org.apache.tools.ant.types.selectors.DepthSelector"> |
| <param name="max" value="1"/> |
| </custom> |
| </fileset> |
| </pre></blockquote> |
| |
| <p>Selects all files in the base directory and one directory below |
| that.</p> |
| |
| <p>For more details concerning writing your own selectors, consult |
| <a href="selectors-program.html">Programming Selectors in Ant</a>.</p> |
| |
| <hr> |
| <p align="center">Copyright © 2002-2004 Apache Software |
| Foundation. All rights Reserved.</p> |
| |
| </body> |
| |
| </html> |