1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
|
<!--
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 AM_or_PM, 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.
<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>
|
