| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html> |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>Selectors in Apache Ant</title> |
| </head> |
| |
| <body> |
| <h2>Selectors</h2> |
| |
| <p>Selectors are a mechanism whereby the files that make up a |
| <code><fileset></code> 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 <code><selector></code> 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 Apache Ant are called |
| <a href="#coreselect"><code>Core Selectors</code></a>. |
| </p> |
| |
| <h3><a name="coreselect">Core Selectors</a></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"><code><contains></code></a> - Select |
| files that contain a particular text string</li> |
| <li><a href="#dateselect"><code><date></code></a> - Select files |
| that have been modified either before or after a particular date |
| and time</li> |
| <li><a href="#dependselect"><code><depend></code></a> - Select files |
| that have been modified more recently than equivalent files |
| elsewhere</li> |
| <li><a href="#depthselect"><code><depth></code></a> - Select files |
| that appear so many directories down in a directory tree</li> |
| <li><a href="#differentselect"><code><different></code></a> - Select files |
| that are different from those elsewhere</li> |
| <li><a href="#filenameselect"><code><filename></code></a> - Select |
| files whose name matches a particular pattern. Equivalent to |
| the include and exclude elements of a patternset.</li> |
| <li><a href="#presentselect"><code><present></code></a> - Select |
| files that either do or do not exist in some other location</li> |
| <li><a href="#regexpselect"><code><containsregexp></code></a> - Select |
| files that match a regular expression</li> |
| <li><a href="#sizeselect"><code><size></code></a> - Select files |
| that are larger or smaller than a particular number of bytes.</li> |
| <li><a href="#typeselect"><code><type></code></a> - Select files |
| that are either regular files or directories.</li> |
| <li><a href="#modified"><code><modified></code></a> - Select files if |
| the return value of the configured algorithm is different from that |
| stored in a cache.</li> |
| <li><a href="#signedselector"><code><signedselector></code></a> - Select files if |
| they are signed, and optionally if they have a signature of a certain name. |
| </li> |
| <li><a href="#scriptselector"><code><scriptselector></code></a> - |
| Use a BSF or JSR 223 scripting language to create |
| your own selector |
| </li> |
| <li><a href="#readable"><code><readable></code></a> - |
| Select files if they are readable.</li> |
| <li><a href="#writable"><code><writable></code></a> - |
| Select files if they are writable.</li> |
| </ul> |
| |
| <h4><a name="containsselect">Contains Selector</a></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> |
| <p>The <code><contains></code> selector can be used as a |
| ResourceSelector (see the |
| <a href="resources.html#restrict"><restrict></a> |
| ResourceCollection).</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> |
| <tr> |
| <td valign="top">encoding</td> |
| <td valign="top">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 |
| </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> |
| |
| |
| <h4><a name="dateselect">Date Selector</a></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. |
| Should be in the format "MM/dd/yyyy hh:mm a" using the US |
| locale, or an alternative pattern specified via |
| the <i>pattern</i> attribute. |
| </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> |
| <tr> |
| <td valign="top">granularity</td> |
| <td valign="top">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. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">pattern</td> |
| <td valign="top">The <CODE>SimpleDateFormat</CODE>-compatible pattern |
| to use when interpreting the <i>datetime</i> attribute using |
| the current locale. |
| <i>Since Ant 1.6.2</i> |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">checkdirs</td> |
| <td valign="top"> |
| Indicates whether or not to check dates on directories. |
| </td> |
| <td valign="top" align="center">No, defaults to <i>false</i></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> |
| |
| |
| <h4><a name="dependselect">Depend Selector</a></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> |
| |
| |
| <h4><a name="depthselect">Depth Selector</a></h4> |
| |
| <p>The <code><depth></code> tag selects files based on |
| how many directory 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> |
| |
| |
| <h4><a name="differentselect">Different Selector</a></h4> |
| |
| <p>The <code><different></code> 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: |
| <ol> |
| <li>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. |
| <li>If a file is only present in targetdir (or after applying the |
| mapper) it is ignored. |
| <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> Unless <tt>ignoreContents</tt> is set to true, |
| 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 <code><copy></code> task, set |
| <tt>preservelastmodified</tt> to <i>true</i> to propagate the timestamp |
| from the source file to the destination file.<p> |
| |
| The <code><different></code> selector 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">ignoreContents</td> |
| <td valign="top">Whether to do a byte per byte compare. |
| Default is false (contents are compared). |
| Since Ant 1.6.3 |
| </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> |
| |
| <h4><a name="filenameselect">Filename Selector</a></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" rowspan="2">Exactly one of |
| the two</td> |
| </tr> |
| <tr> |
| <td valign="top">regex</td> |
| <td valign="top">The regular expression matching files to select.</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> |
| |
| |
| <h4><a name="presentselect">Present Selector</a></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 <code><not></code> |
| 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> |
| |
| <h4><a name="regexpselect">Regular Expression Selector</a></h4> |
| |
| <p>The <code><containsregexp></code> 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 <code>expression</code> attribute. |
| </p> |
| <p>The <code><containsregexp></code> selector can be used as a |
| ResourceSelector (see the |
| <a href="resources.html#restrict"><restrict></a> |
| ResourceCollection).</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> |
| <tr> |
| <td valign="top">casesensitive</td> |
| <td valign="top">Perform a case sensitive match. Default is |
| true. <em>since Ant 1.8.2</em></td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">multiline</td> |
| <td valign="top"> |
| Perform a multi line match. |
| Default is false. <em>since Ant 1.8.2</em></td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">singleline</td> |
| <td valign="top"> |
| 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. <em>since Ant 1.8.2</em></td> |
| <td valign="top" align="center">No</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). |
| |
| |
| <h4><a name="sizeselect">Size Selector</a></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 equal. |
| <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> |
| |
| <h4><a name="typeselect">Type Selector</a></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> |
| |
| |
| <h4><a name="modified">Modified Selector</a></h4> |
| <p>The <code><modified></code> 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> |
| <p>The comparison, computing of the hashvalue and the store is done by implementation |
| of special interfaces. Therefore they may provide additional parameters.</p> |
| |
| <p>The <code><modified></code> selector can be used as a |
| ResourceSelector (see the |
| <a href="resources.html#restrict"><restrict></a> |
| ResourceCollection). |
| In that case it maps simple file resources to files and does its job. If the |
| resource is from another type, the <code><modified></code> selector tries |
| to (<b>attention!</b>) copy the content into a local file for computing the |
| hashvalue.</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> |
| <li> checksum - ChecksumAlgorithm </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 |
| <!-- NOTE --> |
| <i>(see <a href="#ModSelNote">note</a> for restrictions)</i> |
| </li> |
| </ul> |
| </td> |
| <td valign="top" align="center"> No, defaults to <i>equal</i> </td> |
| </tr> |
| <tr> |
| <td valign="top"> algorithmclass </td> |
| <td valign="top"> Classname of custom algorithm implementation. Lower |
| priority than <i>algorithm</i>. </td> |
| <td valign="top" align="center"> No </td> |
| </tr> |
| <tr> |
| <td valign="top"> cacheclass </td> |
| <td valign="top"> Classname of custom cache implementation. Lower |
| priority than <i>cache</i>. </td> |
| <td valign="top" align="center"> No </td> |
| </tr> |
| <tr> |
| <td valign="top"> comparatorclass </td> |
| <td valign="top"> Classname of custom comparator implementation. Lower |
| priority than <i>comparator</i>. </td> |
| <td valign="top" align="center"> No </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> |
| <tr> |
| <td valign="top"> selres </td> |
| <td valign="top"> Should Resources without an InputStream, and |
| therefore without checking, be selected? (boolean) </td> |
| <td valign="top" align="center"> No, defaults to <i>true</i>. Only relevant |
| when used as ResourceSelector. </td> |
| </tr> |
| <tr> |
| <td valign="top"> delayupdate </td> |
| <td valign="top"> If set to <i>true</i>, 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 <i>false</i>, the storage of the cache will happen with each change. This |
| attribute depends upon the <i>update</i> attribute. (boolean)</td> |
| <td valign="top" align="center"> No, defaults to <i>true</i> </td> |
| </tr> |
| </table> |
| |
| <p>These attributes can be set with nested <code><param/></code> tags. With <code><param/></code> |
| 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 comparator </li> |
| <li> <b> algorithmclass </b>: same as attribute algorithmclass </li> |
| <li> <b> cacheclass </b>: same as attribute cacheclass </li> |
| <li> <b> comparatorclass </b>: same as attribute comparatorclass </li> |
| <li> <b> update </b>: same as attribute update </li> |
| <li> <b> seldirs </b>: same as attribute seldirs </li> |
| <li> <b> algorithm.* </b>: Value is transferred to the algorithm via its |
| <i>set</i>XX-methods </li> |
| <li> <b> cache.* </b>: Value is transferred to the cache via its |
| <i>set</i>XX-methods </li> |
| <li> <b> comparator.* </b>: Value is transferred to the comparator via its |
| <i>set</i>XX-methods </li> |
| </ul> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr><td colspan="2"><font size="+1"><b> Algorithm options</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 valign="top"> checksum </td> |
| <td valign="top"> Uses java.util.zip.Checksum. This Algorithm supports |
| the following attributes: |
| <ul> |
| <li><i>algorithm.algorithm</i> (optional): Name of the algorithm |
| (e.g. 'CRC' or 'ADLER', default = <i>CRC</i>) </li> |
| </ul> |
| </td> |
| </tr> |
| <tr><td colspan="2"><font size="+1"><b> Cache options </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 options</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. |
| <!-- NOTE --> |
| <i>(see <a href="#ModSelNote">note</a> for restrictions)</i> |
| </td> |
| </tr> |
| </table> |
| |
| <p>The <code><modified></code> selector supports a nested |
| <code><classpath></code> element that represents a <a href="../using.html#path"> |
| PATH like structure</a> for finding custom interface implementations. </p> |
| |
| <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> |
| |
| <blockquote><pre> |
| <modified cacheclassname="com.mycompany.MyCache"> |
| <classpath> |
| <pathelement location="lib/mycompany-antutil.jar"/> |
| </classpath> |
| </modified> |
| </pre></blockquote> |
| <p>Uses <tt>com.mycompany.MyCache</tt> from a jar outside of Ants own classpath |
| as cache implementation</p> |
| |
| <h4><a name="ModSelNote">Note on RuleBasedCollator</a></h4> |
| <p>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 :-).</p> |
| |
| <h4><a name="signedselector">Signed Selector</a></h4> |
| |
| <p> |
| The <code><signedselector></code> tag selects signed files and optionally |
| signed with a certain name. |
| </p> |
| <p> |
| This selector has been added in Apache Ant 1.7. |
| </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 signature name to check for.</td> |
| <td valign="top" align="center">no</td> |
| </tr> |
| </table> |
| |
| <h4><a name="readable">Readable Selector</a></h4> |
| |
| <p>The <code><readable></code> selector selects only files |
| that are readable. Ant only invokes |
| <code>java.io.File#canRead</code> so if a file is unreadable |
| but the Java VM cannot detect this state, this selector will |
| still select the file.</p> |
| |
| <h4><a name="writable">Writable Selector</a></h4> |
| |
| <p>The <code><writable></code> selector selects only files |
| that are writable. Ant only invokes |
| <code>java.io.File#canWrite</code> so if a file is unwritable |
| but the Java VM cannot detect this state, this selector will |
| still select the file.</p> |
| |
| <h4><a name="scriptselector">Script Selector</a></h4> |
| |
| <p> |
| The <code><scriptselector></code> element enables you |
| to write a complex selection algorithm in any |
| <a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a> |
| or |
| <a href="https://scripting.dev.java.net">JSR 223</a> |
| supported language. |
| See the <a href="../Tasks/script.html">Script</a> task for |
| an explanation of scripts and dependencies. |
| </p> |
| <p> |
| This selector was added in Apache Ant 1.7. |
| </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">language</td> |
| <td valign="top">language of the script.</td> |
| <td valign="top" align="center">yes</td> |
| </tr> |
| <tr> |
| <td valign="top">manager</td> |
| <td valign="top"> |
| The script engine manager to use. |
| See the <a href="../Tasks/script.html">script</a> task |
| for using this attribute. |
| </td> |
| <td valign="top" align="center">No - default is "auto"</td> |
| </tr> |
| <tr> |
| <td valign="top">src</td> |
| <td valign="top">filename of the script</td> |
| <td valign="top" align="center">no</td> |
| </tr> |
| <tr> |
| <td valign="top">setbeans</td> |
| <td valign="top">whether to have all properties, references and targets as |
| global variables in the script.</td> |
| <td valign="top" align="center">No, default is "true".</td> |
| </tr> |
| <tr> |
| <td valign="top">classpath</td> |
| <td valign="top"> |
| The classpath to pass into the script. |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">classpathref</td> |
| <td valign="top">The classpath to use, given as a |
| <a href="../using.html#references">reference</a> to a path defined elsewhere. |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <p> |
| This selector can take a nested <classpath> element. |
| See the <a href="../Tasks/script.html">script</a> task |
| on how to use this element. |
| </p> |
| <p> |
| If no <code>src</code> attribute is supplied, the script must be nested |
| inside the selector declaration. |
| </p> |
| <p>The embedded script is invoked for every test, with |
| the bean <code>self</code> |
| is bound to the selector. It has an attribute <code>selected</code> |
| must can be set using <code>setSelected(boolean)</code> to select that |
| file. |
| |
| <p> |
| |
| The following beans are configured for every script, alongside |
| the classic set of project, properties, and targets. |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Bean</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td valign="top"><b>Type</b></td> |
| </tr> |
| <tr> |
| <td valign="top">self</td> |
| <td valign="top">selector instance</td> |
| <td valign="top">org.apache.tools.ant.types.optional</td> |
| </tr> |
| <tr> |
| <td valign="top">filename</td> |
| <td valign="top">filename of the selection</td> |
| <td valign="top" >String</td> |
| </tr> |
| <tr> |
| <td valign="top">file</td> |
| <td valign="top">file of the selection</td> |
| <td valign="top" >java.io.File</td> |
| </tr> |
| <tr> |
| <td valign="top">basedir</td> |
| <td valign="top">Fileset base directory</td> |
| <td valign="top" >java.io.File</td> |
| </tr> |
| |
| </table> |
| <p> |
| The <code>self</code> bean maps to the selector, which has the following |
| attributes. Only the <code>selected</code> flag is writable, the rest |
| are read only via their getter methods. |
| |
| <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>Type</b></td> |
| </tr> |
| <tr> |
| <td valign="top">selected</td> |
| <td valign="top">writeable flag to select this file</td> |
| <td valign="top" align="center">boolean</td> |
| </tr> |
| <tr> |
| <td valign="top">filename</td> |
| <td valign="top">filename of the selection</td> |
| <td valign="top" >String</td> |
| </tr> |
| <tr> |
| <td valign="top">file</td> |
| <td valign="top">file of the selection</td> |
| <td valign="top" >java.io.File</td> |
| </tr> |
| <tr> |
| <td valign="top">basedir</td> |
| <td valign="top">Fileset base directory</td> |
| <td valign="top" >java.io.File</td> |
| </tr> |
| </table> |
| |
| <p> |
| Example |
| </p> |
| <pre> |
| <scriptselector language="javascript"> |
| self.setSelected(true); |
| </scriptselector> |
| </pre> |
| <p> |
| Selects every file. |
| </p> |
| |
| <pre> |
| <scriptselector language="javascript"> |
| self.setSelected((filename.length%2)==0); |
| </scriptselector> |
| </pre> |
| Select files whose filename length is even. |
| |
| <h3><a name="selectcontainers">Selector Containers</a></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"><code><and></code></a> - select a file only if all |
| the contained selectors select it. |
| <li><a href="#majorityselect"><code><majority></code></a> - select a file |
| if a majority of its selectors select it. |
| <li><a href="#noneselect"><code><none></code></a> - select a file only if |
| none of the contained selectors select it. |
| <li><a href="#notselect"><code><not></code></a> - can contain only one |
| selector, and reverses what it selects and doesn't select. |
| <li><a href="#orselect"><code><or></code></a> - selects a file if any one |
| of the contained selectors selects it. |
| <li><a href="#selectorselect"><code><selector></code></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><code><and></code></li> |
| <li><code><contains></code></li> |
| <li><code><custom></code></li> |
| <li><code><date></code></li> |
| <li><code><depend></code></li> |
| <li><code><depth></code></li> |
| <li><code><filename></code></li> |
| <li><code><majority></code></li> |
| <li><code><none></code></li> |
| <li><code><not></code></li> |
| <li><code><or></code></li> |
| <li><code><present></code></li> |
| <li><code><selector></code></li> |
| <li><code><size></code></li> |
| </ul> |
| |
| <h4><a name="andselect">And Selector</a></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 millennium. |
| </p> |
| |
| |
| <h4><a name="majorityselect">Majority Selector</a></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> |
| |
| |
| <h4><a name="noneselect">None Selector</a></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> |
| |
| |
| <h4><a name="notselect">Not Selector</a></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> |
| |
| |
| <h4><a name="orselect">Or Selector</a></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> |
| |
| |
| <h4><a name="selectorselect">Selector Reference</a></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 <a href="../properties.html#if+unless">if the named |
| property is set</a>. |
| </td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">unless</td> |
| <td valign="top">Allow files to be selected only <a href="../properties.html#if+unless">if the named |
| property is <b>not</b> set</a>. |
| </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> |
| |
| <h3><a name="customselect">Custom Selectors</a></h3> |
| |
| <p>You can write your own selectors and use them within the selector |
| containers by specifying them within the <code><custom></code> 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 <code><param></code> 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> |
| |
| |
| |
| </body> |
| |
| </html> |