选择器

选择器是一种机制，它允许根据除文件名之外的其他条件选择构成 <fileset> 的文件，这些条件由 <include> 和 <exclude> 标签提供。

如何使用选择器

选择器是 FileSet 的一个元素，出现在 FileSet 中。它也可以在任何目标之外定义，方法是使用 <selector> 标签，然后将其用作引用。

不同的选择器具有不同的属性。一些选择器可以包含其他选择器，这些选择器称为 选择器容器。还有一类选择器允许用户定义扩展，称为 自定义选择器。内置于 Apache Ant 的选择器称为 核心选择器。

核心选择器

核心选择器是 Ant 中自带的选择器。它们可以在 fileset 中使用，也可以包含在选择器容器中。

核心选择器是

• <contains>—选择包含特定文本字符串的文件
• <date>—选择在特定日期和时间之前或之后修改的文件
• <depend>—选择比其他地方的等效文件修改时间更晚的文件
• <depth>—选择在目录树中向下出现指定目录级别的文件
• <different>—选择与其他地方不同的文件
• <filename>—选择其名称与特定模式匹配的文件。相当于 patternset 的 include 和 exclude 元素。
• <present>—选择在其他位置存在或不存在的文件
• <containsregexp>—选择与正则表达式匹配的文件
• <size>—选择大小大于或小于特定字节数的文件。
• <type>—选择是普通文件还是目录的文件。
• <modified>—如果配置的算法的返回值与存储在缓存中的返回值不同，则选择文件。
• <signedselector>—如果文件已签名，并且可选地具有特定名称的签名，则选择文件。
• <scriptselector>—使用 BSF 或 JSR 223 脚本语言创建自己的选择器
• <readable>—如果文件可读，则选择文件。
• <writable>—如果文件可写，则选择文件。
• <executable>—如果文件可执行，则选择文件。
• <symlink>—如果文件是符号链接，则选择文件。
• <ownedBy>—如果文件由给定用户拥有，则选择文件。
• <posixGroup>—如果文件具有给定的 POSIX 组，则选择文件。
• <posixPermissions>—如果文件具有给定的 POSIX 权限，则选择文件。

包含选择器

FileSet 中的 <contains> 标签将该 fileset 定义的文件限制为仅包含 text 属性指定的字符串的文件。

<contains> 选择器可以用作 ResourceSelector（参见 <restrict> ResourceCollection）。

以下是如何使用包含选择器的示例

<fileset dir="${doc.path}" includes="**/*.html">
    <contains text="script" casesensitive="no"/>
</fileset>

选择所有包含字符串 script 的 HTML 文件。

日期选择器

FileSet 中的 <date> 标签将对 include 标签指定的文件进行限制，因此最后修改日期不符合选择器指定的日期限制的标签最终不会被选中。

以下是如何使用日期选择器的示例

<fileset dir="${jar.path}" includes="**/*.jar">
    <date datetime="01/01/2001 12:00 AM" when="before"/>
</fileset>

选择所有在 2001 年 1 月 1 日午夜之前最后修改的 JAR 文件。

依赖选择器

<depend> 标签选择最后修改日期比另一个位置的另一个等效文件更晚的文件。

<depend> 标签支持使用包含的 <mapper> 元素来定义要比较的文件的位置。如果没有指定 <mapper> 元素，则使用 identity 类型映射器。

<depend> 选择器区分大小写。

以下是如何使用依赖选择器的示例

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <depend targetdir="${ant.1.4.1}/src/main"/>
</fileset>

选择在 1.5 版本中修改的所有 Java 源文件。

深度选择器

<depth> 标签根据文件相对于 fileset 的基目录的目录级别深度来选择文件。

以下是如何使用深度选择器的示例

<fileset dir="${doc.path}" includes="**/*">
    <depth max="1"/>
</fileset>

选择基目录和基目录下方的所有文件。

不同选择器

如果 <different> 选择器认为文件与另一个位置的等效文件“不同”，则会选择该文件。确定两个文件之间差异的规则如下

1. 如果文件仅存在于您应用选择器的资源集合中，而不在 targetdir 中（或在应用映射器之后），则会选择该文件。
2. 如果文件仅存在于 targetdir 中（或在应用映射器之后），则会忽略该文件。
3. 长度不同的文件是不同的。
4. 如果 ignoreFileTimes 被设置为 off，则不同的文件时间戳会导致文件被视为不同。
5. 除非 ignoreContents 设置为 true，否则会对两个文件进行逐字节检查。

对于无法正确处理依赖项检查的程序和任务，这是一个有用的选择器；即使前置任务始终创建其输出文件，后续任务也可以从使用不同选择器制作的副本中驱动，因此它们的依赖项取决于文件的绝对状态，而不仅仅是时间戳。例如：从网站获取的任何内容，或某些程序的输出。为了减少检查量，在 <copy> 任务中使用此任务时，将 preservelastmodified 设置为 true 以将时间戳从源文件传播到目标文件。

<different> 选择器支持使用包含的 <mapper> 元素来定义要比较的文件的位置。如果没有指定 <mapper> 元素，则使用 identity 类型映射器。

以下是如何使用不同选择器的示例

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <different targetdir="${ant.1.4.1}/src/main"
        ignoreFileTimes="true"/>
</fileset>

比较 1.4.1 和 1.5 版本之间的所有 Java 源文件，并选择那些不同的文件，忽略文件时间。

文件名选择器

<filename> 标签的作用类似于 fileset 中的 <include> 和 <exclude> 标签。但是，通过使用选择器，可以将其与所有其他选择器结合使用，使用任何所需的选择器容器。

<filename> 选择器区分大小写。

以下是如何使用文件名选择器的示例

<fileset dir="${doc.path}" includes="**/*">
    <filename name="**/*.css"/>
</fileset>

选择所有层叠样式表文件。

存在选择器

<present> 标签选择在另一个目录树中具有等效文件的那些文件。

<present> 标签支持使用包含的 <mapper> 元素来定义要测试的文件的位置。如果没有指定 <mapper> 元素，则使用 identity 类型映射器。

<present> 选择器区分大小写。

以下是如何使用 Present 选择器的示例

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <present present="srconly" targetdir="${ant.1.4.1}/src/main"/>
</fileset>

选择 1.5 版本中新增的所有 Java 源文件。

正则表达式选择器

FileSet 中的 <containsregexp> 标签将该 fileset 定义的文件限制为仅那些内容包含与 expression 属性指定的正则表达式匹配的文件。

<containsregexp> 选择器可用作 ResourceSelector（参见 <restrict> ResourceCollection）。

以下是如何使用正则表达式选择器的示例

<fileset dir="${doc.path}" includes="*.txt">
    <containsregexp expression="[4-6]\.[0-9]"/>
</fileset>

选择所有与正则表达式匹配的文本文件（有 4、5 或 6 后面跟着一个点和一个 0 到 9 之间的数字）。

大小选择器

FileSet 中的 <size> 标签将对 include 标签指定的文件进行限制，以便不满足选择器指定的大小限制的标签最终不会被选中。

以下是如何使用大小选择器的示例

<fileset dir="${jar.path}">
  <patternset>
    <include name="**/*.jar"/>
  </patternset>
  <size value="4" units="Ki" when="more"/>
</fileset>

选择所有大于 4096 字节的 JAR 文件。

类型选择器

<type> 标签选择特定类型的文件：目录或常规文件。

以下是如何使用类型选择器仅选择 ${src} 中的目录的示例

<fileset dir="${src}">
  <type type="dir"/>
</fileset>

类型选择器通常与其他选择器结合使用。例如，要选择也存在于 template 目录中的文件，但避免选择空目录，请使用

<fileset dir="${src}">
    <and>
        <present targetdir="template"/>
        <type type="file"/>
    </and>
</fileset>

修改选择器

<modified> 选择器计算文件的值，将其与存储在缓存中的值进行比较，如果这两个值不同，则选择该文件。

由于此选择器高度可配置，因此选择执行的顺序为

1. 获取文件的绝对路径
2. 从配置的缓存中获取缓存的值（绝对路径作为键）
3. 从配置的算法中获取新值
4. 使用配置的比较器比较这两个值
5. 根据需要和请求更新缓存
6. 根据比较结果进行选择

比较、哈希值的计算和存储由特殊接口的实现完成。因此，它们可能提供其他参数。

<modified> 选择器可用作 ResourceSelector（参见 <restrict> ResourceCollection）。在这种情况下，它将简单文件资源映射到文件并执行其工作。如果资源来自其他类型，<modified> 选择器会尝试（注意！）将内容复制到本地文件以计算哈希值。

如果源资源不是文件系统资源，则修改选择器会将其下载到 临时目录。

作为嵌套元素指定的参数

<modified> 选择器支持一个嵌套的 <classpath> 元素，它表示用于查找自定义接口实现的 路径状结构。

<modified> 选择器的所有属性都可以使用嵌套的 <param/> 标签设置。根据以下规则，可以使用 <param/> 标签设置其他值。

algorithm

与 algorithm 属性相同，具有以下附加值

cache

与 cache 属性相同，具有以下附加值

comparator

与 comparator 属性相同。

algorithmclass

与 algorithmclass 属性相同。

comparatorclass

与 comparatorclass 属性相同。

cacheclass

与 cacheclass 属性相同。

update

与 update 属性相同。

seldirs

与 comparatorclass 属性相同。

示例

以下是如何使用修改选择器的一些示例

<copy todir="dest">
    <fileset dir="src">
        <modified/>
    </fileset>
</copy>

这将复制 src 中所有内容已更改的文件到 dest。使用更新的 PropertyfileCache 和 cache.properties 以及 MD5-DigestAlgorithm。

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

这是将同一个示例重写为 CoreSelector，并设置所有值（与默认值相同）。

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

这是将同一个示例重写为 CustomSelector。

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

此选择器在构建环境中用于生成主页（例如，使用 Apache Forrest）的实用场景。这里所有已更改的文件都上传到服务器。因此，CacheSelector 节省了大量的上传时间。

<modified cacheclassname="com.mycompany.MyCache">
    <classpath>
        <pathelement location="lib/mycompany-antutil.jar"/>
    </classpath>
</modified>

使用来自 Ant 自身类路径之外的 jar 的 com.mycompany.MyCache 作为缓存实现

关于 RuleBasedCollator 的注释

RuleBasedCollator 需要一种格式来完成其工作，但在实例化时需要它。在这种情况下，初始化算法存在问题。因此，您不应使用它（或告诉我解决方法 :-）。

签名选择器

<signedselector> 标签选择已签名的文件，并可选地选择使用特定名称签名的文件。

自 Apache Ant 1.7 起

可读选择器

<readable> 选择器仅选择可读的文件。Ant 仅调用 java.io.File#canRead，因此如果文件不可读，但 JVM 无法检测到此状态，则此选择器仍将选择该文件。

可写选择器

<writable> 选择器仅选择可写文件。Ant 仅调用 java.io.File#canWrite，因此如果文件不可写，但 JVM 无法检测到此状态，则此选择器仍将选择该文件。

可执行选择器

<executable> 选择器仅选择可执行文件。Ant 仅调用 java.nio.file.Files#isExecutable，因此如果文件不可执行，但 JVM 无法检测到此状态，则此选择器仍将选择该文件。

自 Ant 1.10.0 起

符号链接选择器

<symlink> 选择器仅选择符号链接。Ant 仅调用 java.nio.file.Files#isSymbolicLink，因此如果文件是符号链接，但 JVM 无法检测到此状态，则此选择器将不会选择该文件。

自 Ant 1.10.0 起

OwnedBy 选择器

<ownedBy> 选择器仅选择由给定用户拥有的文件。Ant 仅调用 java.nio.file.Files#getOwner，因此如果文件系统不支持此操作，则此选择器将不会选择该文件。

自 Ant 1.10.0 起

PosixGroup 选择器

<posixGroup> 选择器仅选择由给定 POSIX 组拥有的文件。Ant 仅调用 java.nio.file.Files#readAttributes，因此如果文件系统不支持该操作或 POSIX 属性，则此选择器将不会选择该文件。

自 Ant 1.10.4 起

PosixPermissions 选择器

<posixPermissions> 选择器仅选择具有给定 POSIX 权限的文件。Ant 仅调用 java.nio.file.Files#getPosixFilePermissions，因此如果文件系统不支持该操作，则此选择器将不会选择该文件。

自 Ant 1.10.4 起

脚本选择器

<scriptselector> 元素使您能够以任何 Apache BSF 或 JSR 223 支持的语言编写复杂的选取算法。有关脚本和依赖项的说明，请参阅 脚本 任务。

自 Apache Ant 1.7 起

此选择器可以接受嵌套的 <classpath> 元素。有关如何使用此元素的信息，请参阅 script 任务。

如果没有提供 src 属性，则脚本必须嵌套在选择器声明中。

嵌入式脚本将针对每次测试调用，其中 bean self 绑定到选择器。它有一个属性 selected，可以使用 setSelected(boolean) 设置它以选择文件。

除了经典的项目、属性和目标集之外，还为每个脚本配置了以下 bean。

self bean 映射到选择器，它具有以下属性。只有 selected 标志是可写的，其余的通过其 getter 方法只读。

示例

<scriptselector language="javascript">
  self.setSelected(true);
</scriptselector>

选择每个文件。

<scriptselector language="javascript">
  self.setSelected((filename.length%2)==0);
</scriptselector>

选择文件名长度为偶数的文件。

选择器容器

为了创建更复杂的选取，您可以使用各种包含其他选择器的选择器。它们以各种方式组合其子选择器的选取。

选择器容器是

• <and>—仅当包含的所有选择器都选择文件时才选择文件。
• <majority>—如果大多数选择器选择文件，则选择文件。
• <none>—仅当包含的任何选择器都没有选择文件时才选择文件。
• <not>—只能包含一个选择器，并反转其选择和未选择的内容。
• <or>—如果包含的任何一个选择器选择文件，则选择文件。
• <selector>—仅包含一个选择器，并在满足任何 "if" 或 "unless" 条件的情况下，将所有请求转发给它，而不进行任何更改。如果您想定义引用，则应使用此选择器。它可以用作 <project> 的元素。如果您希望文件的选择依赖于 Ant 属性设置，则也应使用它。

所有选择器容器都可以包含任何其他选择器，包括其他容器，作为元素。使用容器，选择器标签可以任意深度。以下是容器中允许的选择器元素的完整列表

• <and>
• <contains>
• <custom>
• <date>
• <depend>
• <depth>
• <filename>
• <majority>
• <none>
• <not>
• <or>
• <present>
• <selector>
• <size>

And 选择器

<and> 标签选择被其包含的所有元素选择的那些文件。它会在找到一个没有选择文件的选择器时立即返回，因此它不保证会检查每个选择器。

以下是如何使用 And 选择器的示例

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

选择所有大于 4096 字节且自上个千年以来未更新的 JAR 文件。

Majority 选择器

<majority> 标签选择文件，前提是包含的元素中大多数也选择它。平局的处理方式由 allowtie 属性指定。

以下是如何使用 Majority 选择器的示例

<fileset dir="${docs}" includes="**/*.html">
    <majority>
        <contains text="project" casesensitive="false"/>
        <contains text="taskdef" casesensitive="false"/>
        <contains text="IntrospectionHelper" casesensitive="true"/>
    </majority>
</fileset>

选择所有包含三个短语 project、taskdef 和 IntrospectionHelper 中至少两个的 HTML 文件（最后一个短语必须完全匹配大小写）。

None 选择器

<none> 标签选择不被其包含的任何元素选择的那些文件。它会在找到一个选择文件的选择器时立即返回，因此它不保证会检查每个选择器。

以下是如何使用 None 选择器的示例

<fileset dir="${src}" includes="**/*.java">
    <none>
        <present targetdir="${dest}"/>
        <present targetdir="${dest}">
            <mapper type="glob" from="*.java" to="*.class"/>
        </present>
    </none>
</fileset>

仅选择 .java 文件，这些文件在 dest 目录中没有等效的 .java 或 .class 文件。

Not 选择器

<not> 标签反转其包含的单个选择器的含义。

以下是如何使用 Not 选择器的示例

<fileset dir="${src}" includes="**/*.java">
    <not>
        <contains text="test"/>
    </not>
</fileset>

选择 src 目录中所有不包含字符串 test 的文件。

Or 选择器

<or> 标签选择被其包含的任何一个元素选择的那些文件。它会在找到一个选择文件的选择器时立即返回，因此它不保证会检查每个选择器。

以下是如何使用 Or 选择器的示例

<fileset dir="${basedir}">
    <or>
        <depth max="0"/>
        <filename name="*.png"/>
        <filename name="*.gif"/>
        <filename name="*.jpg"/>
    </or>
</fileset>

选择顶层目录中的所有文件以及它下面的所有图像文件。

选择器引用

<selector> 标签用于创建可以通过引用重复使用的选择器。它是唯一可以作为 <project> 标签的元素，在任何目标之外使用的选择器。它只能包含另一个选择器，但当然，该选择器可以是容器。

<selector> 标签还可以用于有条件地选择文件，具体取决于 Ant 属性是否存在。此功能通过 if 和 unless 属性实现，与它们在目标或 <patternset> 中的 <include> 和 <exclude> 标签上的使用方式完全相同。

以下是如何使用选择器引用的示例

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

将所有具有与之关联的最新等效类文件和 javadoc 文件的 java 文件压缩在一起。

以及根据属性是否设置有条件地选择文件的示例

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

一个有条件地包含 Java 源文件和测试源文件和类文件的 fileset。

自定义选择器

您可以编写自己的选择器，并在 <custom> 标签中指定它们，从而在选择器容器中使用它们。

首先，您必须用 Java 编写选择器类。为了成为选择器，它必须满足的唯一要求是它实现了 org.apache.tools.ant.types.selectors.FileSelector 接口，该接口包含一个方法。有关更多信息，请参阅 在 Ant 中编程选择器。

编写完成后，您可以使用 <custom> 标签将其包含在构建文件中。

以下是如何使用 <custom> 将您的类用作选择器的示例

<fileset dir="${mydir}" includes="**/*">
    <custom classname="com.mydomain.MySelector">
        <param name="myattribute" value="myvalue"/>
    </custom>
</fileset>

许多核心选择器也可以通过使用 <param> 元素指定其属性来用作自定义选择器。它们是

• Contains 选择器，其类名为 org.apache.tools.ant.types.selectors.ContainsSelector
• Date 选择器，其类名为 org.apache.tools.ant.types.selectors.DateSelector
• Depth 选择器，其类名为 org.apache.tools.ant.types.selectors.DepthSelector
• Filename 选择器，其类名为 org.apache.tools.ant.types.selectors.FilenameSelector
• Size 选择器，其类名为 org.apache.tools.ant.types.selectors.SizeSelector

以下是 Depth 选择器部分中的示例，改写为通过 <custom> 使用选择器。

<fileset dir="${doc.path}" includes="**/*">
    <custom classname="org.apache.tools.ant.types.selectors.DepthSelector">
        <param name="max" value="1"/>
    </custom>
</fileset>

选择基目录和基目录下方的所有文件。

有关编写自己的选择器的更多详细信息，请参阅 在 Ant 中编程选择器。