Debian Codegraph @

manual/Types/selectors.html

raw
1 <!DOCTYPE html>
2 <!--
3 Licensed to the Apache Software Foundation (ASF) under one or more
4 contributor license agreements. See the NOTICE file distributed with
5 this work for additional information regarding copyright ownership.
6 The ASF licenses this file to You under the Apache License, Version 2.0
7 (the "License"); you may not use this file except in compliance with
8 the License. You may obtain a copy of the License at
9
10 https://www.apache.org/licenses/LICENSE-2.0
11
12 Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS,
14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 See the License for the specific language governing permissions and
16 limitations under the License.
17 -->
18 <html lang="en">
19 <head>
20 <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
21 <title>Selectors in Apache Ant</title>
22 </head>
23
24 <body>
25 <h2>Selectors</h2>
26
27 <p>Selectors are a mechanism whereby the files that make up a <code>&lt;fileset&gt;</code> can
28 be selected based on criteria other than filename as provided by
29 the <code>&lt;include&gt;</code> and <code>&lt;exclude&gt;</code> tags.</p>
30
31 <h3>How to use a Selector</h3>
32
33 <p>A selector is an element of FileSet, and appears within it. It can also be defined outside of
34 any target by using the <code>&lt;selector&gt;</code> tag and then using it as a reference.</p>
35
36 <p>Different selectors have different attributes. Some selectors can contain other selectors,
37 and these are called <a href="#selectcontainers"><q>Selector Containers</q></a>. There is also
38 a category of selectors that allow user-defined extensions,
39 called <a href="#customselect"><q>Custom Selectors</q></a>. The ones built in to Apache Ant are
40 called <a href="#coreselect"><q>Core Selectors</q></a>.</p>
41
42 <h3 id="coreselect">Core Selectors</h3>
43
44 <p>Core selectors are the ones that come standard with Ant. They can be used within a
45 fileset and can be contained within Selector Containers.</p>
46
47 <p>The core selectors are:</p>
48
49 <ul>
50 <li><a href="#containsselect"><code>&lt;contains&gt;</code></a>&mdash;Select files that
51 contain a particular text string</li>
52 <li><a href="#dateselect"><code>&lt;date&gt;</code></a>&mdash;Select files that have been
53 modified either before or after a particular date and time</li>
54 <li><a href="#dependselect"><code>&lt;depend&gt;</code></a>&mdash;Select files that have been
55 modified more recently than equivalent files elsewhere</li>
56 <li><a href="#depthselect"><code>&lt;depth&gt;</code></a>&mdash;Select files that appear so
57 many directories down in a directory tree</li>
58 <li><a href="#differentselect"><code>&lt;different&gt;</code></a>&mdash;Select files that are
59 different from those elsewhere</li>
60 <li><a href="#filenameselect"><code>&lt;filename&gt;</code></a>&mdash;Select files whose name
61 matches a particular pattern. Equivalent to the include and exclude elements of a
62 patternset.</li>
63 <li><a href="#presentselect"><code>&lt;present&gt;</code></a>&mdash;Select files that either
64 do or do not exist in some other location</li>
65 <li><a href="#regexpselect"><code>&lt;containsregexp&gt;</code></a>&mdash;Select files that
66 match a regular expression</li>
67 <li><a href="#sizeselect"><code>&lt;size&gt;</code></a>&mdash;Select files that are larger or
68 smaller than a particular number of bytes.</li>
69 <li><a href="#typeselect"><code>&lt;type&gt;</code></a>&mdash;Select files that are either
70 regular files or directories.</li>
71 <li><a href="#modified"><code>&lt;modified&gt;</code></a>&mdash;Select files if the return
72 value of the configured algorithm is different from that stored in a cache.</li>
73 <li><a href="#signedselector"><code>&lt;signedselector&gt;</code></a>&mdash;Select files if
74 they are signed, and optionally if they have a signature of a certain name.</li>
75 <li><a href="#scriptselector"><code>&lt;scriptselector&gt;</code></a>&mdash;Use a BSF or JSR
76 223 scripting language to create your own selector</li>
77 <li><a href="#readable"><code>&lt;readable&gt;</code></a>&mdash;Select files if they are
78 readable.</li>
79 <li><a href="#writable"><code>&lt;writable&gt;</code></a>&mdash;Select files if they are
80 writable.</li>
81 <li><a href="#executable"><code>&lt;executable&gt;</code></a>&mdash;Select files if they
82 are executable.</li>
83 <li><a href="#symlink"><code>&lt;symlink&gt;</code></a>&mdash;Select files if they are
84 symlinks.</li>
85 <li><a href="#ownedBy"><code>&lt;ownedBy&gt;</code></a>&mdash;Select files if they are owned
86 by a given user.</li>
87 <li><a href="#posixGroup"><code>&lt;posixGroup&gt;</code></a>&mdash;Select
88 files if they have a given POSIX group.</li>
89 <li><a href="#posixPermissions"><code>&lt;posixPermissions&gt;</code></a>&mdash;Select
90 files if they have given POSIX permissions.</li>
91 <li><a href="#windowsjunction"><code>&lt;windowsjunction&gt;</code></a>&mdash;Select files if they are
92 Windows junctions.</li>
93 </ul>
94
95 <h4 id="containsselect">Contains Selector</h4>
96
97 <p>The <code>&lt;contains&gt;</code> tag in a FileSet limits the files defined by that fileset
98 to only those which contain the string specified by the <code>text</code> attribute.</p>
99 <p>The <code>&lt;contains&gt;</code> selector can be used as a ResourceSelector (see
100 the <a href="resources.html#restrict">&lt;restrict&gt;</a> ResourceCollection).</p>
101
102 <table class="attr">
103 <tr>
104 <th scope="col">Attribute</th>
105 <th scope="col">Description</th>
106 <th scope="col">Required</th>
107 </tr>
108 <tr>
109 <td>text</td>
110 <td>Specifies the text that every file must contain
111 </td>
112 <td>Yes</td>
113 </tr>
114 <tr>
115 <td>casesensitive</td>
116 <td>Whether to pay attention to case when looking for the string in the <var>text</var>
117 attribute.</td>
118 <td>No; default is <q>true</q></td>
119 </tr>
120 <tr>
121 <td>ignorewhitespace</td>
122 <td>Whether to eliminate whitespace before checking for the string in the <var>text</var>
123 attribute.</td>
124 <td>No; default is <q>false</q></td>
125 </tr>
126 <tr>
127 <td>encoding</td>
128 <td>Encoding of the resources being selected.
129 <em>Since Ant 1.9.0</em>
130 </td>
131 <td>No; defaults to default JVM character encoding</td>
132 </tr>
133 </table>
134
135 <p>Here is an example of how to use the Contains Selector:</p>
136
137 <pre>
138 &lt;fileset dir=&quot;${doc.path}&quot; includes=&quot;**/*.html&quot;&gt;
139 &lt;contains text=&quot;script&quot; casesensitive=&quot;no&quot;/&gt;
140 &lt;/fileset&gt;</pre>
141
142 <p>Selects all the HTML files that contain the string <code>script</code>.</p>
143
144 <h4 id="dateselect">Date Selector</h4>
145
146 <p>The <code>&lt;date&gt;</code> tag in a FileSet will put a limit on the files specified by the
147 include tag, so that tags whose last modified date does not meet the date limits specified by
148 the selector will not end up being selected.</p>
149
150 <table class="attr">
151 <tr>
152 <th scope="col">Attribute</th>
153 <th scope="col">Description</th>
154 <th scope="col">Required</th>
155 </tr>
156 <tr>
157 <td>datetime</td>
158 <td>Specifies the date and time to test for. Should be in the format <q>MM/dd/yyyy hh:mm
159 a</q> using the US locale, or an alternative pattern specified via the <var>pattern</var>
160 attribute.
161 </td>
162 <td rowspan="2">At least one of the two</td>
163 </tr>
164 <tr>
165 <td>millis</td>
166 <td class="left">The number of milliseconds since 1970 that should be tested for. It is
167 usually much easier to use the <var>datetime</var> attribute.
168 </td>
169 </tr>
170 <tr>
171 <td>when</td>
172 <td>Indicates how to interpret the date, whether the files to be selected are those
173 whose last modified times should be before, after, or equal to the specified
174 value. Acceptable values for this attribute are:
175 <ul>
176 <li><q>before</q>&mdash;select files whose last modified date is before the indicated
177 date</li>
178 <li><q>after</q>&mdash;select files whose last modified date is after the indicated
179 date</li>
180 <li><q>equal</q>&mdash;select files whose last modified date is this exact date</li>
181 </ul></td>
182 <td>No; default is <q>equal</q></td>
183 </tr>
184 <tr>
185 <td>granularity</td>
186 <td>The number of milliseconds leeway to use when comparing file modification times. This is
187 needed because not every file system supports tracking the last modified time to the
188 millisecond level.</td>
189 <td>No; default is 0 milliseconds, or 2 seconds on DOS systems</td>
190 </tr>
191 <tr>
192 <td>pattern</td>
193 <td>The <code>SimpleDateFormat</code>-compatible pattern to use when interpreting
194 the <var>datetime</var> attribute using the current locale.
195 <em>Since Ant 1.6.2</em></td>
196 <td>No</td>
197 </tr>
198 <tr>
199 <td>checkdirs</td>
200 <td>Indicates whether or not to check dates on directories.</td>
201 <td>No; defaults to <q>false</q></td>
202 </tr>
203 </table>
204
205 <p>Here is an example of how to use the Date Selector:</p>
206
207 <pre>
208 &lt;fileset dir=&quot;${jar.path}&quot; includes=&quot;**/*.jar&quot;&gt;
209 &lt;date datetime=&quot;01/01/2001 12:00 AM&quot; when=&quot;before&quot;/&gt;
210 &lt;/fileset&gt;</pre>
211
212 <p>Selects all JAR files which were last modified before midnight January 1, 2001.</p>
213
214 <h4 id="dependselect">Depend Selector</h4>
215
216 <p>The <code>&lt;depend&gt;</code> tag selects files whose last modified date is later than
217 another, equivalent file in another location.</p>
218
219 <p>The <code>&lt;depend&gt;</code> tag supports the use of a
220 contained <a href="mapper.html"><code>&lt;mapper&gt;</code></a> element to define the location
221 of the file to be compared against. If no <code>&lt;mapper&gt;</code> element is specified,
222 the <code>identity</code> type mapper is used.</p>
223
224 <p>The <code>&lt;depend&gt;</code> selector is case-sensitive.</p>
225
226 <table class="attr">
227 <tr>
228 <th scope="col">Attribute</th>
229 <th scope="col">Description</th>
230 <th scope="col">Required</th>
231 </tr>
232 <tr>
233 <td>targetdir</td>
234 <td>The base directory to look for the files to compare against. The precise location
235 depends on a combination of this attribute and the <code>&lt;mapper&gt;</code> element, if
236 any.</td>
237 <td>Yes</td>
238 </tr>
239 <tr>
240 <td>granularity</td>
241 <td>The number of milliseconds leeway to give before deciding a file is out of date. This is
242 needed because not every file system supports tracking the last modified time to the
243 millisecond level.</td>
244 <td>No; default is 0 milliseconds, or 2 seconds on DOS systems</td>
245 </tr>
246 </table>
247
248 <p>Here is an example of how to use the Depend Selector:</p>
249
250 <pre>
251 &lt;fileset dir=&quot;${ant.1.5}/src/main&quot; includes=&quot;**/*.java&quot;&gt;
252 &lt;depend targetdir=&quot;${ant.1.4.1}/src/main&quot;/&gt;
253 &lt;/fileset&gt;</pre>
254
255 <p>Selects all the Java source files which were modified in the 1.5 release.</p>
256
257 <h4 id="depthselect">Depth Selector</h4>
258
259 <p>The <code>&lt;depth&gt;</code> tag selects files based on how many directory levels deep they
260 are in relation to the base directory of the fileset.</p>
261
262 <table class="attr">
263 <tr>
264 <th scope="col">Attribute</th>
265 <th scope="col">Description</th>
266 <th scope="col">Required</th>
267 </tr>
268 <tr>
269 <td>min</td>
270 <td>The minimum number of directory levels below the base directory that a file must be in
271 order to be selected.</td>
272 <td rowspan="2">At least one of the two; default is no limit</td>
273 </tr>
274 <tr>
275 <td>max</td>
276 <td class="left">The maximum number of directory levels below the base directory that a file
277 can be and still be selected.</td>
278 </tr>
279 </table>
280
281 <p>Here is an example of how to use the Depth Selector:</p>
282
283 <pre>
284 &lt;fileset dir=&quot;${doc.path}&quot; includes=&quot;**/*&quot;&gt;
285 &lt;depth max=&quot;1&quot;/&gt;
286 &lt;/fileset&gt;</pre>
287
288 <p>Selects all files in the base directory and one directory below that.</p>
289
290 <h4 id="differentselect">Different Selector</h4>
291
292 <p>The <code>&lt;different&gt;</code> selector will select a file if it is deemed to be
293 'different' from an equivalent file in another location. The rules for determining difference
294 between the two files are as follows:<p>
295 <ol>
296 <li>If a file is only present in the resource collection you apply the selector to but not
297 in <var>targetdir</var> (or after applying the mapper) the file is selected.</li>
298 <li>If a file is only present in <var>targetdir</var> (or after applying the mapper) it is
299 ignored.</li>
300 <li>Files with different lengths are different.</li>
301 <li>If <var>ignoreFileTimes</var> is turned <q>off</q>, then differing file timestamps will
302 cause files to be regarded as different.</li>
303 <li>Unless <var>ignoreContents</var> is set to <q>true</q>, a byte-for-byte check is run against
304 the two files.</li>
305 </ol>
306 <p>This is a useful selector to work with programs and tasks that don't handle dependency
307 checking properly; even if a predecessor task always creates its output files, followup tasks
308 can be driven off copies made with a different selector, so their dependencies are driven on the
309 absolute state of the files, not just a timestamp. For example: anything fetched from a web
310 site, or the output of some program. To reduce the amount of checking, when using this task
311 inside a <code>&lt;copy&gt;</code> task, set <var>preservelastmodified</var> to <q>true</q> to
312 propagate the timestamp from the source file to the destination file.</p>
313
314 <p>The <code>&lt;different&gt;</code> selector supports the use of a
315 contained <a href="mapper.html"><code>&lt;mapper&gt;</code></a> element to define the location
316 of the file to be compared against. If no <code>&lt;mapper&gt;</code> element is specified,
317 the <code>identity</code> type mapper is used.</p>
318
319 <table class="attr">
320 <tr>
321 <th scope="col">Attribute</th>
322 <th scope="col">Description</th>
323 <th scope="col">Required</th>
324 </tr>
325 <tr>
326 <td>targetdir</td>
327 <td>The base directory to look for the files to compare against. The precise location
328 depends on a combination of this attribute and the <code>&lt;mapper&gt;</code> element, if
329 any.</td>
330 <td>Yes</td>
331 </tr>
332 <tr>
333 <td>ignoreFileTimes</td>
334 <td>Whether to use file times in the comparison or not.</td>
335 <td>No; default is <q>true</q> (time differences are ignored)</td>
336 </tr>
337 <tr>
338 <td>ignoreContents</td>
339 <td>Whether to do a byte per byte compare.
340 <em>Since Ant 1.6.3</em></td>
341 <td>No; default is <q>false</q> (contents are compared)</td>
342 </tr>
343 <tr>
344 <td>granularity</td>
345 <td>The number of milliseconds leeway to give before deciding a file is out of date. This is
346 needed because not every file system supports tracking the last modified time to the
347 millisecond level.</td>
348 <td>No; default is 0 milliseconds, or 2 seconds on DOS systems</td>
349 </tr>
350 </table>
351
352 <p>Here is an example of how to use the Different Selector:</p>
353
354 <pre>
355 &lt;fileset dir=&quot;${ant.1.5}/src/main&quot; includes=&quot;**/*.java&quot;&gt;
356 &lt;different targetdir=&quot;${ant.1.4.1}/src/main&quot;
357 ignoreFileTimes="true"/&gt;
358 &lt;/fileset&gt;</pre>
359
360 <p>Compares all the Java source files between the 1.4.1 and the 1.5 release and selects those
361 who are different, disregarding file times.</p>
362
363 <h4 id="filenameselect">Filename Selector</h4>
364
365 <p>The <code>&lt;filename&gt;</code> tag acts like the <code>&lt;include&gt;</code>
366 and <code>&lt;exclude&gt;</code> tags within a fileset. By using a selector instead, however,
367 one can combine it with all the other selectors using
368 whatever <a href="#selectcontainers">selector container</a> is desired.</p>
369
370 <p>The <code>&lt;filename&gt;</code> selector is case-sensitive.</p>
371
372 <table class="attr">
373 <tr>
374 <th scope="col">Attribute</th>
375 <th scope="col">Description</th>
376 <th scope="col">Required</th>
377 </tr>
378 <tr>
379 <td>name</td>
380 <td>The name of files to select. The name parameter can contain the standard Ant wildcard
381 characters.</td>
382 <td rowspan="2">Exactly one of the two</td>
383 </tr>
384 <tr>
385 <td>regex</td>
386 <td class="left">The regular expression matching files to select.</td>
387 </tr>
388 <tr>
389 <td>casesensitive</td>
390 <td>Whether to pay attention to case when looking at file names.</td>
391 <td>No; default is <q>true</q></td>
392 </tr>
393 <tr>
394 <td>negate</td>
395 <td>Whether to reverse the effects of this filename selection, therefore emulating
396 an <code>exclude</code> rather than <code>include</code> tag.</td>
397 <td>No; default is <q>false</q></td>
398 </tr>
399 </table>
400
401 <p>Here is an example of how to use the Filename Selector:</p>
402
403 <pre>
404 &lt;fileset dir=&quot;${doc.path}&quot; includes=&quot;**/*&quot;&gt;
405 &lt;filename name=&quot;**/*.css&quot;/&gt;
406 &lt;/fileset&gt;</pre>
407
408 <p>Selects all the cascading style sheet files.</p>
409
410 <h4 id="presentselect">Present Selector</h4>
411
412 <p>The <code>&lt;present&gt;</code> tag selects files that have an equivalent file in
413 another directory tree.</p>
414
415 <p>The <code>&lt;present&gt;</code> tag supports the use of a
416 contained <a href="mapper.html"><code>&lt;mapper&gt;</code></a> element to define the location
417 of the file to be tested against. If no <code>&lt;mapper&gt;</code> element is specified,
418 the <code>identity</code> type mapper is used.</p>
419
420 <p>The <code>&lt;present&gt;</code> selector is case-sensitive.</p>
421
422 <table class="attr">
423 <tr>
424 <th scope="col">Attribute</th>
425 <th scope="col">Description</th>
426 <th scope="col">Required</th>
427 </tr>
428 <tr>
429 <td>targetdir</td>
430 <td>The base directory to look for the files to compare against. The precise location
431 depends on a combination of this attribute and the <code>&lt;mapper&gt;</code> element, if
432 any.</td>
433 <td>Yes</td>
434 </tr>
435 <tr>
436 <td>present</td>
437 <td>Whether we are requiring that a file is present in the source directory tree only, or in
438 both the source and the target directory tree. Valid values are:
439 <ul>
440 <li><q>srconly</q>&mdash;select files only if they are in the source directory tree but
441 not in the target directory tree</li>
442 <li><q>both</q >-- select files only if they are present both in the source and target
443 directory trees</li>
444 </ul>
445 Setting this attribute to <q>srconly</q> is equivalent to wrapping the selector in
446 the <code>&lt;not&gt;</code> selector container.</td>
447 <td>No; default is <q>both</q></td>
448 </tr>
449 </table>
450
451 <p>Here is an example of how to use the Present Selector:</p>
452
453 <pre>
454 &lt;fileset dir=&quot;${ant.1.5}/src/main&quot; includes=&quot;**/*.java&quot;&gt;
455 &lt;present present=&quot;srconly&quot; targetdir=&quot;${ant.1.4.1}/src/main&quot;/&gt;
456 &lt;/fileset&gt;</pre>
457
458 <p>Selects all the Java source files which are new in the 1.5 release.</p>
459
460 <h4 id="regexpselect">Regular Expression Selector</h4>
461
462 <p>The <code>&lt;containsregexp&gt;</code> tag in a FileSet limits the files defined by that
463 fileset to only those which contents contain a match to the regular expression specified by
464 the <code>expression</code> attribute.</p>
465
466 <p>The <code>&lt;containsregexp&gt;</code> selector can be used as a ResourceSelector (see
467 the <a href="resources.html#restrict">&lt;restrict&gt;</a> ResourceCollection).</p>
468
469 <table class="attr">
470 <tr>
471 <th scope="col">Attribute</th>
472 <th scope="col">Description</th>
473 <th scope="col">Required</th>
474 </tr>
475 <tr>
476 <td>expression</td>
477 <td>Specifies the regular expression that must match true in every file</td>
478 <td>Yes</td>
479 </tr>
480 <tr>
481 <td>casesensitive</td>
482 <td>Perform a case sensitive match. <em>Since Ant 1.8.2</em></td>
483 <td>No; default is <q>true</q></td>
484 </tr>
485 <tr>
486 <td>multiline</td>
487 <td>Perform a multi line match. <em>Since Ant 1.8.2</em></td>
488 <td>No; default is <q>false</q></td>
489 </tr>
490 <tr>
491 <td>singleline</td>
492 <td>This allows <q>.</q> to match new lines. SingleLine is not to be confused with
493 multiline, SingleLine is a perl regex term, it corresponds to dotall in Java regex.
494 <em>Since Ant 1.8.2</em></td>
495 <td>No; default is <q>false</q></td>
496 </tr>
497 </table>
498
499 <p>Here is an example of how to use the regular expression Selector:</p>
500
501 <pre>
502 &lt;fileset dir=&quot;${doc.path}&quot; includes=&quot;*.txt&quot;&gt;
503 &lt;containsregexp expression=&quot;[4-6]\.[0-9]&quot;/&gt;
504 &lt;/fileset&gt;</pre>
505
506 <p>Selects all the text files that match the regular expression (have a 4, 5 or 6 followed by a
507 period and a number from 0 to 9).
508
509 <h4 id="sizeselect">Size Selector</h4>
510
511 <p>The <code>&lt;size&gt;</code> tag in a FileSet will put a limit on the files specified by the
512 include tag, so that tags which do not meet the size limits specified by the selector will not
513 end up being selected.</p>
514
515 <table class="attr">
516 <tr>
517 <th scope="col">Attribute</th>
518 <th scope="col">Description</th>
519 <th scope="col">Required</th>
520 </tr>
521 <tr>
522 <td>value</td>
523 <td>The size of the file which should be tested for.
524 </td>
525 <td>Yes</td>
526 </tr>
527 <tr>
528 <td>units</td>
529 <td>The units that the <code>value</code> attribute is expressed in. When using the standard
530 single letter SI designations, such as <q>k</q>, <q>M</q>, or <q>G</q>, multiples of 1000
531 are used. If you want to use power of 2 units, use the IEC standard: <q>Ki</q> for
532 1024, <q>Mi</q> for 1048576, and so on. The default is no units, which means
533 the <var>value</var> attribute expresses the exact number of bytes.</td>
534 <td>No</td>
535 </tr>
536 <tr>
537 <td>when</td>
538 <td>Indicates how to interpret the size, whether the files to be selected should be larger,
539 smaller, or equal to that value. Acceptable values for this attribute are:
540 <ul>
541 <li><q>less</q>&mdash;select files less than the indicated size</li>
542 <li><q>more</q>&mdash;select files greater than the indicated size</li>
543 <li><q>equal</q>&mdash;select files this exact size</li>
544 </ul></td>
545 <td>No; default is <q>equal</q></td>
546 </tr>
547 </table>
548
549 <p>Here is an example of how to use the Size Selector:</p>
550
551 <pre>
552 &lt;fileset dir=&quot;${jar.path}&quot;&gt;
553 &lt;patternset&gt;
554 &lt;include name=&quot;**/*.jar&quot;/&gt;
555 &lt;/patternset&gt;
556 &lt;size value=&quot;4&quot; units=&quot;Ki&quot; when=&quot;more&quot;/&gt;
557 &lt;/fileset&gt;</pre>
558
559 <p>Selects all JAR files that are larger than 4096 bytes.</p>
560
561 <h4 id="typeselect">Type Selector</h4>
562
563 <p>The <code>&lt;type&gt;</code> tag selects files of a certain type: directory or
564 regular.</p>
565
566 <table class="attr">
567 <tr>
568 <th scope="col">Attribute</th>
569 <th scope="col">Description</th>
570 <th scope="col">Required</th>
571 </tr>
572 <tr>
573 <td>type</td>
574 <td>The type of file which should be tested for. Acceptable values are:
575 <ul>
576 <li><q>file</q>&mdash;regular files</li>
577 <li><q>dir</q>&mdash;directories</li>
578 </ul></td>
579 <td>Yes</td>
580 </tr>
581 </table>
582
583 <p>Here is an example of how to use the Type Selector to select only directories
584 in <code>${src}</code></p>
585
586 <pre>
587 &lt;fileset dir=&quot;${src}&quot;&gt;
588 &lt;type type="dir"/&gt;
589 &lt;/fileset&gt;</pre>
590
591 <p>The Type Selector is often used in conjunction with other selectors. For example, to select
592 files that also exist in a <samp>template</samp> directory, but avoid selecting empty
593 directories, use:</p>
594
595 <pre>
596 &lt;fileset dir="${src}"&gt;
597 &lt;and&gt;
598 &lt;present targetdir="template"/&gt;
599 &lt;type type="file"/&gt;
600 &lt;/and&gt;
601 &lt;/fileset&gt;</pre>
602
603 <h4 id="modified">Modified Selector</h4>
604 <p>The <code>&lt;modified&gt;</code> selector computes a value for a file, compares that to the
605 value stored in a cache and select the file, if these two values differ.</p>
606 <p>Because this selector is highly configurable the order in which the selection is done is:</p>
607 <ol>
608 <li>get the absolute path for the file</li>
609 <li>get the cached value from the configured cache (absolute path as key)</li>
610 <li>get the new value from the configured algorithm</li>
611 <li>compare these two values with the configured comparator</li>
612 <li>update the cache if needed and requested</li>
613 <li>do the selection according to the comparison result</li>
614 </ol>
615 <p>The comparison, computing of the hashvalue and the store is done by implementation of special
616 interfaces. Therefore they may provide additional parameters.</p>
617
618 <p>The <code>&lt;modified&gt;</code> selector can be used as a ResourceSelector (see
619 the <a href="resources.html#restrict">&lt;restrict&gt;</a> ResourceCollection). In that case it
620 maps simple file resources to files and does its job. If the resource is from another type,
621 the <code>&lt;modified&gt;</code> selector tries to (<strong>attention!</strong>) copy the
622 content into a local file for computing the hashvalue.</p>
623
624 <p>If the source resource is not a filesystem resource the
625 modified selector will download it to
626 the <a href="../running.html#tmpdir">temporary directory</a>.</p>
627
628 <table class="attr">
629 <tr>
630 <th scope="col">Attribute</th>
631 <th scope="col">Description</th>
632 <th scope="col">Required</th>
633 </tr>
634 <tr>
635 <td>algorithm</td>
636 <td>The type of algorithm should be used. Acceptable values are (further information
637 see later):
638 <ul>
639 <li><q>hashvalue</q>&mdash;HashvalueAlgorithm</li>
640 <li><q>digest</q>&mdash;DigestAlgorithm</li>
641 <li><q>checksum</q>&mdash;ChecksumAlgorithm</li>
642 <li><q>lastmodified</q>&mdash;LastModifiedAlgorithm</li>
643 </ul>
644 </td>
645 <td>No; defaults to <q>digest</q></td>
646 </tr>
647 <tr>
648 <td>cache</td>
649 <td>The type of cache should be used. Acceptable values are (further information see
650 later):
651 <ul>
652 <li><q>propertyfile</q>&mdash;PropertyfileCache</li>
653 </ul>
654 </td>
655 <td>No; defaults to <q>propertyfile</q></td>
656 </tr>
657 <tr>
658 <td>comparator</td>
659 <td>The type of comparator should be used. Acceptable values are:
660 <ul>
661 <li><q>equal</q>&mdash;EqualComparator</li>
662 <li><q>rule</q>&mdash;java.text.RuleBasedCollator
663 <!-- NOTE -->
664 <em>(see <a href="#ModSelNote">note</a> for restrictions)</em></li>
665 </ul>
666 </td>
667 <td>No; defaults to <q>equal</q></td>
668 </tr>
669 <tr>
670 <td>algorithmclass</td>
671 <td>Classname of custom algorithm implementation. Lower priority
672 than <var>algorithm</var>.</td>
673 <td>No</td>
674 </tr>
675 <tr>
676 <td>cacheclass</td>
677 <td>Classname of custom cache implementation. Lower priority than <var>cache</var>.</td>
678 <td>No</td>
679 </tr>
680 <tr>
681 <td>comparatorclass</td>
682 <td>Classname of custom comparator implementation. Lower priority
683 than <var>comparator</var>.</td>
684 <td>No</td>
685 </tr>
686 <tr>
687 <td>update</td>
688 <td>Should the cache be updated when values differ? (boolean)</td>
689 <td>No; defaults to <q>true</q></td>
690 </tr>
691 <tr>
692 <td>seldirs</td>
693 <td>Should directories be selected? (boolean)</td>
694 <td>No; defaults to <q>true</q></td>
695 </tr>
696 <tr>
697 <td>selres</td>
698 <td>Should Resources without an InputStream, and therefore without checking, be selected?
699 (boolean)</td>
700 <td>No; defaults to <q>true</q>. Only relevant when used as ResourceSelector.</td>
701 </tr>
702 <tr>
703 <td>delayupdate</td>
704 <td>If set to <q>true</q>, the storage of the cache will be delayed until the next finished
705 BuildEvent; task finished, target finished or build finished, whichever comes first. This
706 is provided for increased performance. If set to <q>false</q>, the storage of the cache
707 will happen with each change. This attribute depends upon the <var>update</var>
708 attribute. (boolean)</td>
709 <td>No; defaults to <q>true</q></td>
710 </tr>
711 </table>
712
713 <h5>Parameters specified as nested elements</h5>
714
715 <p>The <code>&lt;modified&gt;</code> selector supports a nested <code>&lt;classpath&gt;</code>
716 element that represents a <a href="../using.html#path">path-like structure</a> for finding
717 custom interface implementations.</p>
718
719 <p>All attributes of a <code>&lt;modified&gt;</code> selector can be set with
720 nested <code>&lt;param/&gt;</code> tags. Additional values can be set
721 with <code>&lt;param/&gt;</code> tags according to the rules below.</p>
722
723 <h6>algorithm</h6>
724 <p>Same as <var>algorithm</var> attribute, with the following additional values:</p>
725 <table>
726 <tr>
727 <th scope="col">Name</th>
728 <th scope="col">Description</th>
729 </tr>
730 <tr>
731 <td>hashvalue</td>
732 <td>Reads the content of a file into a <code>java.lang.String</code> and uses
733 that <code>hashValue()</code>. No additional configuration required.</td>
734 </tr>
735 <tr>
736 <td>digest</td>
737 <td>Uses <code>java.security.MessageDigest</code>. This Algorithm supports the following
738 attributes:
739 <ul>
740 <li><var>algorithm.algorithm</var> (optional): Name of the Digest algorithm
741 (e.g. <q>MD5</q> or <q>SHA</q>); default is <q>MD5</q></li>
742 <li><var>algorithm.provider</var> (optional): Name of the Digest provider; default
743 is <q>null</q></li>
744 </ul>
745 </td>
746 </tr>
747 <tr>
748 <td>checksum</td>
749 <td>Uses <code>java.util.zip.Checksum</code>. This Algorithm supports the following
750 attributes:
751 <ul>
752 <li><var>algorithm.algorithm</var> (optional): Name of the algorithm (e.g. <q>CRC</q>
753 or <q>ADLER</q>); default is <q>CRC</q>)</li>
754 </ul>
755 </td>
756 </tr>
757 <tr>
758 <td>lastmodified</td>
759 <td>Uses the lastModified property of a file. No additional configuration is required.</td>
760 </tr>
761 </table>
762 <h6>cache</h6>
763 <p>Same as <var>cache</var> attribute, with the following additional values:</p>
764 <table>
765 <tr>
766 <th scope="col">Name</th>
767 <th scope="col">Description</th>
768 </tr>
769 <tr>
770 <td>propertyfile</td>
771 <td>Use the <code>java.util.Properties</code> class and its possibility to load and store to
772 file. This Cache implementation supports the following attributes:
773 <ul>
774 <li><var>cache.cachefile</var> (optional): Name of the properties file; default
775 is <q>cache.properties</q></li>
776 </ul>
777 </td>
778 </tr>
779 </table>
780 <h6>comparator</h6>
781 <p>Same as <var>comparator</var> attribute.</p>
782 <h6>algorithmclass</h6>
783 <p>Same as <var>algorithmclass</var> attribute.</p>
784 <h6>comparatorclass</h6>
785 <p>Same as <var>comparatorclass</var> attribute.</p>
786 <h6>cacheclass</h6>
787 <p>Same as <var>cacheclass</var> attribute.</p>
788 <h6>update</h6>
789 <p>Same as <var>update</var> attribute.</p>
790 <h6>seldirs</h6>
791 <p>Same as <var>comparatorclass</var> attribute.</p>
792
793 <h5>Examples</h5>
794 <p>Here are some examples of how to use the Modified Selector:</p>
795
796 <pre>
797 &lt;copy todir="dest"&gt;
798 &lt;fileset dir="src"&gt;
799 &lt;modified/&gt;
800 &lt;/fileset&gt;
801 &lt;/copy&gt;</pre>
802
803 <p>This will copy all files from <samp>src</samp> to <samp>dest</samp> which content has
804 changed. Using an updating PropertyfileCache with <samp>cache.properties</samp> and
805 MD5-DigestAlgorithm.</p>
806
807 <pre>
808 &lt;copy todir="dest"&gt;
809 &lt;fileset dir="src"&gt;
810 &lt;modified update="true"
811 seldirs="true"
812 cache="propertyfile"
813 algorithm="digest"
814 comparator="equal"&gt;
815 &lt;param name="cache.cachefile" value="cache.properties"/&gt;
816 &lt;param name="algorithm.algorithm" value="MD5"/&gt;
817 &lt;/modified&gt;
818 &lt;/fileset&gt;
819 &lt;/copy&gt;</pre>
820
821 <p>This is the same example rewritten as CoreSelector with setting the all the values (same as
822 defaults are).</p>
823
824 <pre>
825 &lt;copy todir="dest"&gt;
826 &lt;fileset dir="src"&gt;
827 &lt;custom class="org.apache.tools.ant.types.selectors.modifiedselector.ModifiedSelector"&gt;
828 &lt;param name="update" value="true"/&gt;
829 &lt;param name="seldirs" value="true"/&gt;
830 &lt;param name="cache" value="propertyfile"/&gt;
831 &lt;param name="algorithm" value="digest"/&gt;
832 &lt;param name="comparator" value="equal"/&gt;
833 &lt;param name="cache.cachefile" value="cache.properties"/&gt;
834 &lt;param name="algorithm.algorithm" value="MD5"/&gt;
835 &lt;/custom&gt;
836 &lt;/fileset&gt;
837 &lt;/copy&gt;</pre>
838
839 <p>And this is the same rewritten as CustomSelector.</p>
840
841 <pre>
842 &lt;target name="generate-and-upload-site"&gt;
843 &lt;echo&gt; generate the site using forrest &lt;/echo&gt;
844 &lt;antcall target="site"/&gt;
845
846 &lt;echo&gt; upload the changed file &lt;/echo&gt;
847 &lt;ftp server="${ftp.server}" userid="${ftp.user}" password="${ftp.pwd}"&gt;
848 &lt;fileset dir="htdocs/manual"&gt;
849 &lt;modified/&gt;
850 &lt;/fileset&gt;
851 &lt;/ftp&gt;
852 &lt;/target&gt;</pre>
853
854 <p>A useful scenario for this selector inside a build environment for homepage generation
855 (e.g. with <a href="https://forrest.apache.org/" target="_top">Apache Forrest</a>). Here
856 all <strong>changed</strong> files are uploaded to the server. The CacheSelector saves therefore
857 much upload time.</p>
858
859 <pre>
860 &lt;modified cacheclassname="com.mycompany.MyCache"&gt;
861 &lt;classpath&gt;
862 &lt;pathelement location="lib/mycompany-antutil.jar"/&gt;
863 &lt;/classpath&gt;
864 &lt;/modified&gt;</pre>
865
866 <p>Uses <code>com.mycompany.MyCache</code> from a jar outside of Ant's own classpath as
867 cache implementation</p>
868
869 <h4 id="ModSelNote">Note on RuleBasedCollator</h4>
870 <p>The RuleBasedCollator needs a format for its work, but its needed while instantiating. There
871 is a problem in the initialization algorithm for this case. Therefore you should not use this
872 (or tell me the workaround :-).</p>
873
874 <h4 id="signedselector">Signed Selector</h4>
875
876 <p>The <code>&lt;signedselector&gt;</code> tag selects signed files and optionally signed with a
877 certain name.</p>
878 <p><em>Since Apache Ant 1.7</em></p>
879 <table class="attr">
880 <tr>
881 <th scope="col">Attribute</th>
882 <th scope="col">Description</th>
883 <th scope="col">Required</th>
884 </tr>
885 <tr>
886 <td>name</td>
887 <td>The signature name to check for.</td>
888 <td>No</td>
889 </tr>
890 </table>
891
892 <h4 id="readable">Readable Selector</h4>
893
894 <p>The <code>&lt;readable&gt;</code> selector selects only files that are readable. Ant only
895 invokes <code class="code">java.io.File#canRead</code> so if a file is unreadable but JVM cannot
896 detect this state, this selector will still select the file.</p>
897
898 <h4 id="writable">Writable Selector</h4>
899
900 <p>The <code>&lt;writable&gt;</code> selector selects only files that are writable. Ant only
901 invokes <code class="code">java.io.File#canWrite</code> so if a file is nonwritable but JVM
902 cannot detect this state, this selector will still select the file.</p>
903
904 <h4 id="executable">Executable Selector</h4>
905
906 <p>The <code>&lt;executable&gt;</code> selector selects only files that are executable. Ant
907 only invokes <code class="code">java.nio.file.Files#isExecutable</code> so if a file is not
908 executable but JVM cannot detect this state, this selector will still select the file.</p>
909
910 <p><em>Since Ant 1.10.0</em></p>
911
912 <h4 id="symlink">Symlink Selector</h4>
913
914 <p>The <code>&lt;symlink&gt;</code> selector selects only files that are symbolic links. Ant
915 only invokes <code class="code">java.nio.file.Files#isSymbolicLink</code> so if a file is a
916 symbolic link but JVM cannot detect this state, this selector will not select the file.</p>
917
918 <p><em>Since Ant 1.10.0</em></p>
919
920 <h4 id="ownedBy">OwnedBy Selector</h4>
921
922 <p>The <code>&lt;ownedBy&gt;</code> selector selects only files that are owned by the given
923 user. Ant only invokes <code class="code">java.nio.file.Files#getOwner</code> so if a file
924 system doesn't support the operation this selector will not select the file.</p>
925
926 <p><em>Since Ant 1.10.0</em></p>
927
928 <table class="attr">
929 <tr>
930 <th scope="col">Attribute</th>
931 <th scope="col">Description</th>
932 <th scope="col">Required</th>
933 </tr>
934 <tr>
935 <td>owner</td>
936 <td>Username of the expected owner</td>
937 <td>Yes</td>
938 </tr>
939 <tr>
940 <td>followsymlinks</td>
941 <td>Must the selector follow symbolic links and Windows junctions? (see also how the attribute interacts with the
942 corresponding attribute of
943 the <a href="fileset.html#symlink">FileSet</a>). Windows junctions are detected since Ant 1.10.16.</td>
944 <td>No; defaults to <q>true</q></td>
945 </tr>
946 </table>
947
948 <h4 id="posixGroup">PosixGroup Selector</h4>
949
950 <p>The <code>&lt;posixGroup&gt;</code> selector selects only files that are owned by the given
951 POSIX group. Ant only invokes <code class="code">java.nio.file.Files#readAttributes</code> so
952 if a file system doesn't support the operation or POSIX attributes this selector will not
953 select the file.</p>
954
955 <p><em>Since Ant 1.10.4</em></p>
956
957 <table class="attr">
958 <tr>
959 <th scope="col">Attribute</th>
960 <th scope="col">Description</th>
961 <th scope="col">Required</th>
962 </tr>
963 <tr>
964 <td>group</td>
965 <td>POSIX group name</td>
966 <td>Yes</td>
967 </tr>
968 <tr>
969 <td>followsymlinks</td>
970 <td>Must the selector follow symbolic links and Windows junctions? (see also how the attribute interacts with the
971 corresponding attribute of
972 the <a href="fileset.html#symlink">FileSet</a>). Windows junctions are detected since Ant 1.10.16.</td>
973 <td>No; defaults to <q>true</q></td>
974 </tr>
975 </table>
976
977 <h4 id="posixPermissions">PosixPermissions Selector</h4>
978
979 <p>The <code>&lt;posixPermissions&gt;</code> selector selects only files that have the given
980 POSIX permissions. Ant only
981 invokes <code class="code">java.nio.file.Files#getPosixFilePermissions</code> so if a file
982 system doesn't support the operation this selector will not select the file.</p>
983
984 <p><em>Since Ant 1.10.4</em></p>
985
986 <table class="attr">
987 <tr>
988 <th scope="col">Attribute</th>
989 <th scope="col">Description</th>
990 <th scope="col">Required</th>
991 </tr>
992 <tr>
993 <td>permissions</td>
994 <td>POSIX permissions in string (<q>rwxrwxrwx</q>) or octal (<q>777</q>) format</td>
995 <td>Yes</td>
996 </tr>
997 <tr>
998 <td>followsymlinks</td>
999 <td>Must the selector follow symbolic links and Windows junctions? (see also how the attribute interacts with the
1000 corresponding attribute of
1001 the <a href="fileset.html#symlink">FileSet</a>). Windows junctions are detected since Ant 1.10.16.</td>
1002 <td>No; defaults to <q>true</q></td>
1003 </tr>
1004 </table>
1005
1006 <h4 id="windowsjunction">Windows Junction Selector</h4>
1007
1008 <p>The <code>&lt;windowsjunction&gt;</code> selector selects only
1009 directories that are Windows junctions.</p>
1010
1011 <p><em>Since Ant 1.10.16</em></p>
1012
1013 <h4 id="scriptselector">Script Selector</h4>
1014
1015 <p>The <code>&lt;scriptselector&gt;</code> element enables you to write a complex selection
1016 algorithm in any <a href="https://jakarta.apache.org/bsf" target="_top">Apache BSF</a>
1017 or <a href="https://jcp.org/aboutJava/communityprocess/maintenance/jsr223/223ChangeLog.html"
1018 target="_top">JSR 223</a> supported language. See the <a href="../Tasks/script.html">Script</a>
1019 task for an explanation of scripts and dependencies.</p>
1020 <p><em>Since Apache Ant 1.7</em></p>
1021 <table class="attr">
1022 <tr>
1023 <th scope="col">Attribute</th>
1024 <th scope="col">Description</th>
1025 <th scope="col">Required</th>
1026 </tr>
1027 <tr>
1028 <td>language</td>
1029 <td>language of the script.</td>
1030 <td>Yes</td>
1031 </tr>
1032 <tr>
1033 <td>manager</td>
1034 <td>The script engine manager to use. See the <a href="../Tasks/script.html">script</a>
1035 task for using this attribute.</td>
1036 <td>No; default is <q>auto</q></td>
1037 </tr>
1038 <tr>
1039 <td>src</td>
1040 <td>filename of the script</td>
1041 <td>No</td>
1042 </tr>
1043 <tr>
1044 <td>encoding</td>
1045 <td>The encoding of the script as a file. <em>since Ant 1.10.2</em></td>
1046 <td>No; defaults to default JVM character encoding</td>
1047 </tr>
1048 <tr>
1049 <td>setbeans</td>
1050 <td>Whether to have all properties, references and targets as global variables in the
1051 script.</td>
1052 <td>No; default is <q>true</q></td>
1053 </tr>
1054 <tr>
1055 <td>classpath</td>
1056 <td>The classpath to pass into the script.</td>
1057 <td>No</td>
1058 </tr>
1059 <tr>
1060 <td>classpathref</td>
1061 <td>The classpath to use, given as a <a href="../using.html#references">reference</a> to
1062 a path defined elsewhere.
1063 <td>No</td>
1064 </tr>
1065 </table>
1066 <p>This selector can take a nested <code>&lt;classpath&gt;</code> element. See
1067 the <a href="../Tasks/script.html">script</a> task on how to use this element.</p>
1068 <p>If no <var>src</var> attribute is supplied, the script must be nested inside the selector
1069 declaration.</p>
1070 <p>The embedded script is invoked for every test, with the bean <code class="code">self</code>
1071 is bound to the selector. It has an attribute <var>selected</var> which can be set
1072 using <code class="code">setSelected(boolean)</code> to select a file.</p>
1073
1074 <p>The following beans are configured for every script, alongside the classic set of project,
1075 properties, and targets.</p>
1076
1077 <table>
1078 <tr>
1079 <th scope="col">Bean</th>
1080 <th scope="col">Description</th>
1081 <th scope="col">Type</th>
1082 </tr>
1083 <tr>
1084 <td>self</td>
1085 <td>selector instance</td>
1086 <td>org.apache.tools.ant.types.optional</td>
1087 </tr>
1088 <tr>
1089 <td>filename</td>
1090 <td>filename of the selection</td>
1091 <td>String</td>
1092 </tr>
1093 <tr>
1094 <td>file</td>
1095 <td>file of the selection</td>
1096 <td>java.io.File</td>
1097 </tr>
1098 <tr>
1099 <td>basedir</td>
1100 <td>Fileset base directory</td>
1101 <td>java.io.File</td>
1102 </tr>
1103 </table>
1104
1105 <p>The <code>self</code> bean maps to the selector, which has the following attributes. Only
1106 the <var>selected</var> flag is writable, the rest are read only via their getter methods.</p>
1107 <table class="attr">
1108 <tr>
1109 <th scope="col">Attribute</th>
1110 <th scope="col">Description</th>
1111 <th scope="col">Type</th>
1112 </tr>
1113 <tr>
1114 <td>selected</td>
1115 <td>writeable flag to select this file</td>
1116 <td>boolean</td>
1117 </tr>
1118 <tr>
1119 <td>filename</td>
1120 <td>filename of the selection</td>
1121 <td>String</td>
1122 </tr>
1123 <tr>
1124 <td>file</td>
1125 <td>file of the selection</td>
1126 <td>java.io.File</td>
1127 </tr>
1128 <tr>
1129 <td>basedir</td>
1130 <td>Fileset base directory</td>
1131 <td>java.io.File</td>
1132 </tr>
1133 </table>
1134
1135 <p>Example</p>
1136 <pre>
1137 &lt;scriptselector language=&quot;javascript&quot;&gt;
1138 self.setSelected(true);
1139 &lt;/scriptselector&gt;</pre>
1140 <p>Selects every file.</p>
1141
1142 <pre>
1143 &lt;scriptselector language=&quot;javascript&quot;&gt;
1144 self.setSelected((filename.length%2)==0);
1145 &lt;/scriptselector&gt;</pre>
1146 <p>Select files whose filename length is even.</p>
1147
1148 <h3 id="selectcontainers">Selector Containers</h3>
1149
1150 <p>To create more complex selections, a variety of selectors that contain other selectors are
1151 available for your use. They combine the selections of their child selectors in various
1152 ways.</p>
1153
1154 <p>The selector containers are:</p>
1155
1156 <ul>
1157 <li><a href="#andselect"><code>&lt;and&gt;</code></a>&mdash;select a file only if all the
1158 contained selectors select it.</li>
1159 <li><a href="#majorityselect"><code>&lt;majority&gt;</code></a>&mdash;select a file if a
1160 majority of its selectors select it.</li>
1161 <li><a href="#noneselect"><code>&lt;none&gt;</code></a>&mdash;select a file only if none
1162 of the contained selectors select it.</li>
1163 <li><a href="#notselect"><code>&lt;not&gt;</code></a>&mdash;can contain only one selector, and
1164 reverses what it selects and doesn't select.</li>
1165 <li><a href="#orselect"><code>&lt;or&gt;</code></a>&mdash;selects a file if any one of the
1166 contained selectors selects it.</li>
1167 <li><a href="#selectorselect"><code>&lt;selector&gt;</code></a>&mdash;contains only one
1168 selector and forwards all requests to it without alteration, provided that
1169 any <code>&quot;if&quot;</code> or <code>&quot;unless&quot;</code> conditions are met. This
1170 is the selector to use if you want to define a reference. It is usable as an element
1171 of <code>&lt;project&gt;</code>. It is also the one to use if you want selection of files to
1172 be dependent on Ant property settings.</li>
1173 </ul>
1174
1175 <p>All selector containers can contain any other selector, including other containers, as an
1176 element. Using containers, the selector tags can be arbitrarily deep. Here is a complete list of
1177 allowable selector elements within a container:</p>
1178
1179 <ul>
1180 <li><code>&lt;and&gt;</code></li>
1181 <li><code>&lt;contains&gt;</code></li>
1182 <li><code>&lt;custom&gt;</code></li>
1183 <li><code>&lt;date&gt;</code></li>
1184 <li><code>&lt;depend&gt;</code></li>
1185 <li><code>&lt;depth&gt;</code></li>
1186 <li><code>&lt;filename&gt;</code></li>
1187 <li><code>&lt;majority&gt;</code></li>
1188 <li><code>&lt;none&gt;</code></li>
1189 <li><code>&lt;not&gt;</code></li>
1190 <li><code>&lt;or&gt;</code></li>
1191 <li><code>&lt;present&gt;</code></li>
1192 <li><code>&lt;selector&gt;</code></li>
1193 <li><code>&lt;size&gt;</code></li>
1194 </ul>
1195
1196 <h4 id="andselect">And Selector</h4>
1197
1198 <p>The <code>&lt;and&gt;</code> tag selects files that are selected by all of the elements it
1199 contains. It returns as soon as it finds a selector that does not select the file, so it is not
1200 guaranteed to check every selector.</p>
1201
1202 <p>Here is an example of how to use the And Selector:</p>
1203
1204 <pre>
1205 &lt;fileset dir=&quot;${dist}&quot; includes=&quot;**/*.jar&quot;&gt;
1206 &lt;and&gt;
1207 &lt;size value=&quot;4&quot; units=&quot;Ki&quot; when=&quot;more&quot;/&gt;
1208 &lt;date datetime=&quot;01/01/2001 12:00 AM&quot; when=&quot;before&quot;/&gt;
1209 &lt;/and&gt;
1210 &lt;/fileset&gt;</pre>
1211
1212 <p>Selects all the JAR file larger than 4096 bytes which haven't been update since the last
1213 millennium.</p>
1214
1215 <h4 id="majorityselect">Majority Selector</h4>
1216
1217 <p>The <code>&lt;majority&gt;</code> tag selects files provided that a majority of the contained
1218 elements also select it. Ties are dealt with as specified by the <var>allowtie</var>
1219 attribute.</p>
1220
1221 <table class="attr">
1222 <tr>
1223 <th scope="col">Attribute</th>
1224 <th scope="col">Description</th>
1225 <th scope="col">Required</th>
1226 </tr>
1227 <tr>
1228 <td>allowtie</td>
1229 <td>Whether files should be selected if there are an even number of selectors selecting them
1230 as are not selecting them.</td>
1231 <td>No; default is <q>true</q></td>
1232 </tr>
1233 </table>
1234
1235 <p>Here is an example of how to use the Majority Selector:</p>
1236
1237 <pre>
1238 &lt;fileset dir=&quot;${docs}&quot; includes=&quot;**/*.html&quot;&gt;
1239 &lt;majority&gt;
1240 &lt;contains text=&quot;project&quot; casesensitive="false"/&gt;
1241 &lt;contains text=&quot;taskdef&quot; casesensitive="false"/&gt;
1242 &lt;contains text=&quot;IntrospectionHelper&quot; casesensitive="true"/&gt;
1243 &lt;/majority&gt;
1244 &lt;/fileset&gt;</pre>
1245
1246 <p>Selects all the HTML files which contain at least two of the three
1247 phrases <q>project</q>, <q>taskdef</q>, and <q>IntrospectionHelper</q> (this last phrase must
1248 match case exactly).</p>
1249
1250 <h4 id="noneselect">None Selector</h4>
1251
1252 <p>The <code>&lt;none&gt;</code> tag selects files that are not selected by any of the elements
1253 it contains. It returns as soon as it finds a selector that selects the file, so it is not
1254 guaranteed to check every selector.</p>
1255
1256 <p>Here is an example of how to use the None Selector:</p>
1257
1258 <pre>
1259 &lt;fileset dir=&quot;${src}&quot; includes=&quot;**/*.java&quot;&gt;
1260 &lt;none&gt;
1261 &lt;present targetdir=&quot;${dest}&quot;/&gt;
1262 &lt;present targetdir=&quot;${dest}&quot;&gt;
1263 &lt;mapper type=&quot;glob&quot; from=&quot;*.java&quot; to=&quot;*.class&quot;/&gt;
1264 &lt;/present&gt;
1265 &lt;/none&gt;
1266 &lt;/fileset&gt;</pre>
1267
1268 <p>Selects only <samp>.java</samp> files which do not have equivalent <samp>.java</samp>
1269 or <samp>.class</samp> files in the <samp>dest</samp> directory.</p>
1270
1271 <h4 id="notselect">Not Selector</h4>
1272
1273 <p>The <code>&lt;not&gt;</code> tag reverses the meaning of the single selector it contains.</p>
1274
1275 <p>Here is an example of how to use the Not Selector:</p>
1276
1277 <pre>
1278 &lt;fileset dir=&quot;${src}&quot; includes=&quot;**/*.java&quot;&gt;
1279 &lt;not&gt;
1280 &lt;contains text=&quot;test&quot;/&gt;
1281 &lt;/not&gt;
1282 &lt;/fileset&gt;</pre>
1283
1284 <p>Selects all the files in the <samp>src</samp> directory that do not contain the
1285 string <q>test</q>.</p>
1286
1287 <h4 id="orselect">Or Selector</h4>
1288
1289 <p>The <code>&lt;or&gt;</code> tag selects files that are selected by any one of the elements it
1290 contains. It returns as soon as it finds a selector that selects the file, so it is not
1291 guaranteed to check every selector.</p>
1292
1293 <p>Here is an example of how to use the Or Selector:</p>
1294
1295 <pre>
1296 &lt;fileset dir=&quot;${basedir}&quot;&gt;
1297 &lt;or&gt;
1298 &lt;depth max=&quot;0&quot;/&gt;
1299 &lt;filename name="*.png"/&gt;
1300 &lt;filename name="*.gif"/&gt;
1301 &lt;filename name="*.jpg"/&gt;
1302 &lt;/or&gt;
1303 &lt;/fileset&gt;</pre>
1304
1305 <p>Selects all the files in the top directory along with all the image files below it.</p>
1306
1307 <h4 id="selectorselect">Selector Reference</h4>
1308
1309 <p>The <code>&lt;selector&gt;</code> tag is used to create selectors that can be reused through
1310 references. It is the only selector which can be used outside of any target, as an element of
1311 the <code>&lt;project&gt;</code> tag. It can contain only one other selector, but of course that
1312 selector can be a container.</p>
1313
1314 <p>The <code>&lt;selector&gt;</code> tag can also be used to select files conditionally based on
1315 whether an Ant property exists or not. This functionality is realized using the <var>if</var>
1316 and <var>unless</var> attributes in exactly the same way they are used on targets or on
1317 the <code>&lt;include&gt;</code> and <code>&lt;exclude&gt;</code> tags within
1318 a <code>&lt;patternset&gt;</code>.</p>
1319
1320 <table class="attr">
1321 <tr>
1322 <th scope="col">Attribute</th>
1323 <th scope="col">Description</th>
1324 <th scope="col">Required</th>
1325 </tr>
1326 <tr>
1327 <td>if</td>
1328 <td>Allow files to be selected only <a href="../properties.html#if+unless">if the named
1329 property is set</a>.
1330 </td>
1331 <td>No</td>
1332 </tr>
1333 <tr>
1334 <td>unless</td>
1335 <td>Allow files to be selected only <a href="../properties.html#if+unless">if the named
1336 property is <strong>not</strong> set</a>.
1337 </td>
1338 <td>No</td>
1339 </tr>
1340 </table>
1341
1342 <p>Here is an example of how to use the Selector Reference:</p>
1343
1344 <pre>
1345 &lt;project default=&quot;all&quot; basedir=&quot;./ant&quot;&gt;
1346
1347 &lt;selector id=&quot;completed&quot;&gt;
1348 &lt;none&gt;
1349 &lt;depend targetdir=&quot;build/classes&quot;&gt;
1350 &lt;mapper type=&quot;glob&quot; from=&quot;*.java&quot; to=&quot;*.class&quot;/&gt;
1351 &lt;/depend&gt;
1352 &lt;depend targetdir=&quot;docs/manual/api&quot;&gt;
1353 &lt;mapper type=&quot;glob&quot; from=&quot;*.java&quot; to=&quot;*.html&quot;/&gt;
1354 &lt;/depend&gt;
1355 &lt;/none&gt;
1356 &lt;/selector&gt;
1357
1358 &lt;target&gt;
1359 &lt;zip&gt;
1360 &lt;fileset dir=&quot;src/main&quot; includes=&quot;**/*.java&quot;&gt;
1361 &lt;selector refid=&quot;completed&quot;/&gt;
1362 &lt;/fileset&gt;
1363 &lt;/zip&gt;
1364 &lt;/target&gt;
1365
1366 &lt;/project&gt;</pre>
1367
1368 <p>Zips up all the java files which have an up-to-date equivalent class file and javadoc file
1369 associated with them.</p>
1370
1371 <p>And an example of selecting files conditionally, based on whether properties are set:</p>
1372
1373 <pre>
1374 &lt;fileset dir=&quot;${working.copy}&quot;&gt;
1375 &lt;or&gt;
1376 &lt;selector if=&quot;include.tests&quot;&gt;
1377 &lt;filename name=&quot;**/*Test.class&quot;&gt;
1378 &lt;/selector&gt;
1379 &lt;selector if=&quot;include.source&quot;&gt;
1380 &lt;and&gt;
1381 &lt;filename name=&quot;**/*.java&quot;&gt;
1382 &lt;not&gt;
1383 &lt;selector unless=&quot;include.tests&quot;&gt;
1384 &lt;filename name=&quot;**/*Test.java&quot;&gt;
1385 &lt;/selector&gt;
1386 &lt;/not&gt;
1387 &lt;/and&gt;
1388 &lt;/selector&gt;
1389 &lt;/or&gt;
1390 &lt;/fileset&gt;</pre>
1391
1392 <p>A fileset that conditionally contains Java source files and Test source and class
1393 files.</p>
1394
1395 <h3 id="customselect">Custom Selectors</h3>
1396
1397 <p>You can write your own selectors and use them within the selector containers by specifying
1398 them within the <code>&lt;custom&gt;</code> tag.</p>
1399
1400 <p>First, you have to write your selector class in Java. The only requirement it must meet in
1401 order to be a selector is that it implements
1402 the <code class="code">org.apache.tools.ant.types.selectors.FileSelector</code> interface, which
1403 contains a single method. See <a href="selectors-program.html">Programming Selectors in Ant</a>
1404 for more information.</p>
1405
1406 <p>Once that is written, you include it in your build file by using
1407 the <code>&lt;custom&gt;</code> tag.</p>
1408
1409 <table class="attr">
1410 <tr>
1411 <th scope="col">Attribute</th>
1412 <th scope="col">Description</th>
1413 <th scope="col">Required</th>
1414 </tr>
1415 <tr>
1416 <td>classname</td>
1417 <td>The name of your class that
1418 implements <code class="code">org.apache.tools.ant.types.selectors.FileSelector</code>.
1419 </td>
1420 <td>Yes</td>
1421 </tr>
1422 <tr>
1423 <td>classpath</td>
1424 <td>The classpath to use in order to load the custom selector class. If
1425 neither <var>classpath</var> nor <var>classpathref</var> are specified, the class will be
1426 loaded from the classpath that Ant uses.</td>
1427 <td>No</td>
1428 </tr>
1429 <tr>
1430 <td>classpathref</td>
1431 <td>A reference to a classpath previously defined. If neither <var>classpathref</var>
1432 nor <var>classpath</var> are specified, the class will be loaded from the classpath that Ant
1433 uses.</td>
1434 <td>No</td>
1435 </tr>
1436 </table>
1437
1438 <p>Here is how you use <code>&lt;custom&gt;</code> to use your class as a selector:</p>
1439
1440 <pre>
1441 &lt;fileset dir=&quot;${mydir}&quot; includes=&quot;**/*&quot;&gt;
1442 &lt;custom classname=&quot;com.mydomain.MySelector&quot;&gt;
1443 &lt;param name=&quot;myattribute&quot; value=&quot;myvalue&quot;/&gt;
1444 &lt;/custom&gt;
1445 &lt;/fileset&gt;</pre>
1446
1447 <p>A number of core selectors can also be used as custom selectors by specifying their
1448 attributes using <code>&lt;param&gt;</code> elements. These are</p>
1449
1450 <ul>
1451 <li><a href="#containsselect">Contains Selector</a> with
1452 classname <code class="code">org.apache.tools.ant.types.selectors.ContainsSelector</code>
1453 <li><a href="#dateselect">Date Selector</a> with
1454 classname <code class="code">org.apache.tools.ant.types.selectors.DateSelector</code>
1455 <li><a href="#depthselect">Depth Selector</a> with
1456 classname <code class="code">org.apache.tools.ant.types.selectors.DepthSelector</code>
1457 <li><a href="#filenameselect">Filename Selector</a> with
1458 classname <code class="code">org.apache.tools.ant.types.selectors.FilenameSelector</code>
1459 <li><a href="#sizeselect">Size Selector</a> with
1460 classname <code class="code">org.apache.tools.ant.types.selectors.SizeSelector</code>
1461 </ul>
1462
1463 <p>Here is the example from the Depth Selector section rewritten to use the selector
1464 through <code>&lt;custom&gt;</code>.</p>
1465
1466 <pre>
1467 &lt;fileset dir=&quot;${doc.path}&quot; includes=&quot;**/*&quot;&gt;
1468 &lt;custom classname=&quot;org.apache.tools.ant.types.selectors.DepthSelector&quot;&gt;
1469 &lt;param name=&quot;max&quot; value=&quot;1&quot;/&gt;
1470 &lt;/custom&gt;
1471 &lt;/fileset&gt;</pre>
1472
1473 <p>Selects all files in the base directory and one directory below that.</p>
1474
1475 <p>For more details concerning writing your own selectors,
1476 consult <a href="selectors-program.html">Programming Selectors in Ant</a>.</p>
1477
1478 </body>
1479 </html>