58、Ant 扩展与安装全攻略

Ant 扩展与安装全攻略

1. 使用自定义选择器进行构建

在构建过程中，我们可以使用自定义选择器。以下是一个示例构建文件：

<project name="selectors" default="main">
  <property name="build.dir" location="build"/>
  <property name="temp.dir" location="${build.dir}/temp"/>
  <property name="src.dir" location="src"/>
  <property name="data.dir" location="data"/>
  <target name="init">
    <mkdir dir="${build.dir}"/>
    <condition property="is.windows">                               
      <os family="windows"/>                                        
    </condition>                                                    
  </target>
  <target name="clean">
    <delete dir="${build.dir}"/>
  </target>
  <target name="compile" depends="init">
    <javac srcdir="${src.dir}" destdir="${build.dir}"/>
  </target>
  <target name="setup-test-init">
    <delete dir="${temp.dir}"/>
    <mkdir dir="${temp.dir}"/>
    <delete dir="${data.dir}"/>
    <mkdir dir="${data.dir}"/>
    <echo file="${data.dir}/writable.dat">writable</echo>           
    <echo file="${data.dir}/nonwritable.dat">nonwritable</echo>     
  </target>
  <target name="setup-test-windows" if="is.windows">                
    <exec executable="cmd.exe">                                     
      <arg line="/c attrib +R"/>                                    
      <arg file="${data.dir}/nonwritable.dat"/>                     
    </exec>                                                         
    <exec executable="cmd.exe">                                     
      <arg line="/c attrib -R"/>                                    
      <arg file="${data.dir}/writable.dat"/>                        
    </exec>                                                         
  </target>                                                         
  <target name="setup-test"                                         
          depends="setup-test-init,setup-test-windows">             
    <chmod file="${data.dir}/nonwritable.dat" perm="u-r"/>          
    <chmod file="${data.dir}/writable.dat" perm="u+r"/>             
  </target>
  <target name="test" depends="compile,setup-test">
    <selector id="selector">                                   
      <custom classname="org.example.antbook.ReadOnlySelector" 
              classpath="${build.dir}"/>                       
    </selector>                                                
    <copy todir="${temp.dir}">
      <fileset dir="${data.dir}">
        <selector refid="selector"/>   
      </fileset>
    </copy>
    <available file="${temp.dir}/writable.dat"
               property="test.failed"/>
    <fail if="test.failed">
       Failed!  Writable file copied!
    </fail>
    <echo>Test passed</echo>
  </target>
  <target name="main" depends="test"/>
</project>

这个构建文件的主要步骤如下：
1. 初始化 ：创建构建目录，并设置 Windows 平台标志。
2. 清理 ：删除构建目录。
3. 编译 ：编译源代码。
4. 测试设置 ：创建测试文件，并设置文件属性。
5. 测试 ：使用自定义选择器复制只读文件，并检查是否复制了可写文件。

如果使用 <not> 选择器容器，可以反转逻辑，只复制可写文件，避免编写两个选择器或对选择器进行参数化。

2. 实现自定义过滤器

我们可以使用自定义过滤器来处理 XML 文件中的特殊字符。以下是一个示例：

<root>
  <description>${description}</description>
</root>

假设 server.properties 文件包含：

description=<some description>

为了避免 XML 文件无效，我们需要对特殊字符进行转义。可以使用自定义的 EscapeFilter 过滤器：

<loadproperties srcfile="${data.dir}/server.properties">
  <filterchain>
    <filterreader classname="org.example.antbook.EscapeFilter"
                  classpath="${build.dir}"
    />
  </filterchain>
</loadproperties>
<echo>description=${description}</echo>
<copy tofile="${build.dir}/server.xml"
      file="${data.dir}/template.xml"
      overwrite="true">
  <filterchain>
    <expandproperties/>
  </filterchain>
</copy>
<xmlvalidate file="${build.dir}/server.xml" lenient="true"/> 

EscapeFilter 的实现如下：

package org.example.antbook;
import org.apache.tools.ant.filters.BaseFilterReader;
import org.apache.tools.ant.filters.ChainableReader;
import java.io.Reader;
import java.io.IOException;
public class EscapeFilter extends BaseFilterReader
    implements ChainableReader {
    private String queuedData = null;
    public EscapeFilter(final Reader in) {
        super(in);
    }
    public Reader chain(Reader rdr) {                               
        EscapeFilter newFilter = new EscapeFilter(rdr);             
        newFilter.setProject(getProject());                         
        return newFilter;                                           
    }                                                               
    public int read() throws IOException {
        if (queuedData != null && queuedData.length() == 0) {
            queuedData = null;
        }
        int ch = -1;
        if (queuedData != null) {                                   
            ch = queuedData.charAt(0);                              
            queuedData = queuedData.substring(1);                   
            if (queuedData.length() == 0) {                         
                queuedData = null;                                  
            }                                                       
        } else {
            ch = in.read();
            if (ch == -1) {                                         
                return ch;                                          
            }                                                       
            queuedData = getEscapeString(ch);
            if (queuedData != null) {
                return read();   
            }
        }
        return ch;
    }
    private String getEscapeString(int ch) {
        String output = null;
        switch (ch) {
            case '<' : output = "&lt;"; break;
            case '>' : output = "&gt;"; break;
            case '"' : output = "&quot"; break;
            case '\'' : output = "&apos;"; break;
        }
        if (output != null) {
            return output;
        }
        if (ch < 32 || ch > 127) {
            return "&#x" + Integer.toHexString(ch) + ";";
        }
        return null;
    }
}

EscapeFilter 的主要逻辑如下：
1. 链式处理 ：实现 ChainableReader 接口，允许过滤器链式处理。
2. 读取字符 ：从输入流中读取字符，并对特殊字符进行转义。
3. 转义字符串 ：根据字符的不同，返回相应的转义字符串。

3. Ant 安装

3.1 安装前准备

在安装 Ant 之前，需要确保已经安装了 Java Development Kit (JDK)，并设置了 JAVA_HOME 环境变量。可以通过以下命令测试 JDK 是否安装成功：

javac

如果出现使用说明，则表示 JDK 安装成功。

3.2 安装步骤

Ant 安装的核心步骤如下：
1. 下载 Ant。
2. 解压到指定目录。
3. 将 Ant 的 bin 目录添加到系统路径。
4. 设置环境变量，指向 JDK 和 Ant。
5. 可选：添加所需的库。

3.3 Windows 安装

1. 从 Apache 网站下载 Ant 二进制文件，并解压到指定目录，例如 c:\java\apps\ant 。
2. 将 c:\java\apps\ant\bin 添加到系统路径。
3. 设置 ANT_HOME 环境变量为 c:\java\apps\ant 。

对于 Windows 9x，需要将环境变量设置在 autoexec.bat 中，并重启系统。对于 Windows NT/2000/XP，可以在系统属性的环境变量中设置。

安装完成后，可以通过以下命令测试：

ant -version

3.4 Unix 安装

1. 下载并安装 JDK，设置 JAVA_HOME 环境变量。
2. 从 Jakarta 网站下载 Ant 构建文件，可以选择 RPM 格式或 tar.gz 格式。
3. 解压文件，例如使用 tar xzf jakarta-ant-1.5-bin.tar.gz 。
4. 设置环境变量，例如在 .profile 或 .bash_profile 中添加以下内容：

export JAVA_HOME= (JDK 安装路径)
export ANT_HOME= (Ant 安装路径)
export PATH=$PATH:$ANT_HOME/bin:$JAVA_HOME/bin

对于 tcsh ，可以在 .cshrc 或 .tcshrc 中设置。

安装完成后，可以通过以下命令测试：

ant -version

4. 安装配置

Ant 包装脚本使用两个有用的环境变量： ANT_OPTS 和 ANT_ARGS 。
- ANT_OPTS ：为执行 Ant 的 JVM 提供选项，例如系统属性和内存配置。例如，在 Windows 上可以设置：

SET ANT_OPTS=-Xmx500M

• ANT_ARGS ：作为命令行参数传递给 Ant 的主进程。例如，如果想使用 NoBannerLogger 去除空目标的输出，可以设置：

SET ANT_ARGS=-logger org.apache.tools.ant.NoBannerLogger

5. 安装故障排除

在安装 Ant 过程中，可能会遇到各种问题，以下是一些常见问题及解决方法：
| 问题 | 测试方法 | 解决方法 |
| — | — | — |
| Java 未安装或配置 | 运行 java 命令，如果不是已知命令，则 Java 未安装或路径错误 | 安装 JDK，并设置 JAVA_HOME 指向安装目录 |
| JDK 未安装或配置 | Ant 启动时会警告 JAVA_HOME 未设置，某些任务可能会失败 | 设置 JAVA_HOME 指向 JDK 安装目录 |
| Ant 不在路径中 | 运行 ant -version ，如果命令解释器提示 ant 未知，则路径错误 | 修改环境路径，包含 Ant 的 bin 目录，并重新加载环境 |
| 路径中有其他版本的 Ant | 运行 ant -version ，如果版本号不匹配，则可能有其他版本的 Ant | 移除或重命名其他版本，或调整路径顺序 |
| Ant 因缺少任务或库而失败 | 查看 ANT_HOME/lib 目录中是否有 optional.jar 文件 | 从 jakarta.apache.org 网站下载该文件，并放入目录 |
| Ant 仍然因缺少任务或库而失败 | 根据错误文本确定失败的任务，查看 Ant 手册了解依赖项，检查 JAR 文件是否存在 | 下载所需的 JAR 文件，并放入 ANT_HOME/lib 目录 |
| ANT_HOME 目录指向错误 | 调用 ant.bat 时出现 lcp.bat 缺失警告，或找不到 ant.jar | 设置 ANT_HOME 为正确的目录，或不设置该变量 |
| 类路径上的 Java 库不兼容 | XML 解析可能失败 | 清空 CLASSPATH 环境变量，或移除 XML 解析器库 |
| Java 扩展库与 Ant 冲突 | 查看 JRE/lib/ext 目录中是否有干扰 Ant 的 JAR 文件 | 将 XML 解析器库移动到其他目录 |
| 运行 Ant 时出现密封违规异常 | 消息会指出有密封问题的库 | 识别冲突并修复，通常是移除其中一个库 |
| 调用 Ant 生成 Java 使用说明 | 检查环境变量是否有明显错误 | 修复明显错误，或逐个取消设置变量，直到 Ant 正常工作 |
| ANT_OPTS 变量中的 Java 选项非法 | 检查 ANT_OPTS 是否包含无效的 JVM 选项 | 修正或清空该变量 |

通过以上步骤和方法，可以顺利扩展和安装 Ant，并解决可能遇到的问题。在进行自定义开发之前，建议熟悉 Ant 的现有功能，很可能 Ant 已经能够满足你的需求。

Ant 扩展与安装全攻略

6. Ant 扩展技术总结

Ant 的扩展技术为开发者提供了强大的功能，能够满足各种复杂的构建需求。以下是对前面介绍的扩展技术的总结：
- 自定义选择器 ：通过自定义选择器，可以实现对文件的精细筛选。在构建过程中，根据文件的属性（如只读、可写）进行选择，提高构建的准确性和效率。使用自定义选择器时，需要在构建文件中定义选择器，并在文件集（fileset）中引用。
- 自定义过滤器 ：自定义过滤器可以处理文件中的特殊字符，确保文件的合法性。例如，在处理 XML 文件时，对特殊字符进行转义，避免文件无效。实现自定义过滤器需要编写 Java 类，并在构建文件中使用 <filterreader> 标签引用。
- 脚本任务 ：虽然文档未详细提及，但 Ant 支持使用 Bean Scripting Framework 支持的语言进行脚本编写。脚本任务可以在 Ant 构建文件中临时编写任务，无需编写、编译和打包自定义 Java 任务。不过，脚本任务的功能和健壮性相对较弱，通常作为原型开发的方法，后续可转换为 Java 任务。
- 构建监听器和日志记录器 ：构建监听器和日志记录器是 Ant 与 IDE 和外部工具集成的关键。Ant 自带了一些监听器和日志记录器，开发者可以根据需要自定义。在进行自定义开发之前，建议熟悉 Ant 文档中已有的监听器和日志记录器，特别是 Log4j 和 Jakarta Commons Logging 监听器，它们具有高度的可配置性，能满足大多数自定义监听需求。
- 自定义映射器 ：自定义映射器用于将一个文件名转换为其他文件名，为 Ant 处理文件集提供了更多的灵活性。在某些特定场景下，自定义映射器可以实现独特的文件名转换逻辑。

7. 扩展技术的应用场景

不同的扩展技术适用于不同的应用场景，以下是一些常见的应用场景：
| 扩展技术 | 应用场景 |
| — | — |
| 自定义选择器 | - 筛选特定属性的文件，如只读文件、隐藏文件等。
- 在大型项目中，根据文件的修改时间、大小等属性进行筛选，提高构建效率。 |
| 自定义过滤器 | - 处理 XML、HTML 等文件中的特殊字符，确保文件的合法性。
- 在配置文件中，对敏感信息进行加密或替换。 |
| 脚本任务 | - 快速实现一些简单的任务，如文件复制、目录清理等。
- 在开发过程中，进行临时的任务测试和验证。 |
| 构建监听器和日志记录器 | - 集成 Ant 到 IDE 中，实时监控构建过程。
- 记录详细的构建日志，方便问题排查和性能分析。 |
| 自定义映射器 | - 在文件重命名、文件路径转换等场景中使用。
- 实现复杂的文件名映射逻辑，如根据文件内容生成新的文件名。 |

8. 扩展技术的实现流程

以下是实现自定义选择器和过滤器的流程图：

graph LR
    classDef startend fill:#F5EBFF,stroke:#BE8FED,stroke-width:2px
    classDef process fill:#E5F6FF,stroke:#73A6FF,stroke-width:2px
    classDef decision fill:#FFF6CC,stroke:#FFBC52,stroke-width:2px

    A([开始]):::startend --> B(需求分析):::process
    B --> C{选择扩展技术}:::decision
    C -->|自定义选择器| D(编写选择器类):::process
    C -->|自定义过滤器| E(编写过滤器类):::process
    D --> F(在构建文件中定义选择器):::process
    E --> G(在构建文件中使用过滤器):::process
    F --> H(测试选择器功能):::process
    G --> I(测试过滤器功能):::process
    H --> J{测试是否通过}:::decision
    I --> J
    J -->|是| K([结束]):::startend
    J -->|否| B

实现扩展技术的具体步骤如下：
1. 需求分析 ：明确需要解决的问题，确定使用哪种扩展技术。
2. 选择扩展技术 ：根据需求选择合适的扩展技术，如自定义选择器、过滤器等。
3. 编写代码 ：根据选择的扩展技术，编写相应的 Java 类。
4. 在构建文件中配置 ：在 Ant 构建文件中使用自定义的选择器、过滤器等。
5. 测试和调试 ：对扩展功能进行测试，确保其正常工作。如果测试不通过，返回需求分析阶段，重新评估和调整。

9. 安装与扩展的注意事项

在安装和扩展 Ant 时，需要注意以下几点：
- Java 环境 ：确保 Java Development Kit (JDK) 已正确安装，并设置了 JAVA_HOME 环境变量。不同的 Ant 任务可能依赖于 JDK 中的工具，如 <javac> 和 <javadoc> 任务需要使用 tools.jar 中的类。
- 路径问题 ：避免在安装路径中使用空格，因为空格可能会导致 Ant 和其他程序出现问题。同时，确保 Ant 的 bin 目录已添加到系统路径中，以便可以从命令行启动 Ant。
- 版本兼容性 ：注意 Ant 与其他 Java 库的版本兼容性。某些 Java 产品可能包含自己的 Ant 版本，这可能会导致冲突。在使用多个版本的 Ant 时，需要确保路径设置正确，避免使用错误的版本。
- 扩展开发 ：在进行扩展开发之前，建议先熟悉 Ant 的现有功能。很多情况下，Ant 自带的功能已经能够满足需求，无需进行自定义开发。同时，在编写自定义选择器、过滤器等时，要注意代码的健壮性和可维护性。
- 环境变量 ：正确设置 ANT_OPTS 和 ANT_ARGS 环境变量。 ANT_OPTS 用于为执行 Ant 的 JVM 提供选项，如内存配置； ANT_ARGS 用于传递命令行参数给 Ant 的主进程。

10. 总结与建议

Ant 是一个强大的构建工具，通过扩展技术可以进一步增强其功能，满足各种复杂的构建需求。在使用 Ant 时，建议遵循以下步骤：
1. 熟悉现有功能 ：在进行自定义开发之前，充分了解 Ant 的现有功能和任务。可以参考 Ant 的官方文档、相关书籍和在线资源，掌握 Ant 的基本用法和常见任务。
2. 选择合适的扩展技术 ：根据具体需求，选择合适的扩展技术，如自定义选择器、过滤器、脚本任务等。在选择扩展技术时，要考虑技术的复杂度、可维护性和性能。
3. 进行测试和验证 ：在实现扩展功能后，进行充分的测试和验证，确保其正常工作。可以编写测试用例，对扩展功能进行单元测试和集成测试。
4. 注意兼容性和稳定性 ：在使用扩展技术时，要注意与其他 Java 库和工具的兼容性，确保系统的稳定性。同时，定期更新 Ant 和相关库的版本，以获取最新的功能和修复。
5. 参考社区资源 ：Ant 拥有庞大的社区，社区中提供了丰富的资源和经验分享。在遇到问题时，可以参考社区论坛、邮件列表等，获取帮助和解决方案。

通过以上的步骤和建议，可以更好地使用和扩展 Ant，提高构建效率和质量。在实际应用中，根据具体项目的需求和特点，灵活运用 Ant 的扩展技术，实现高效、稳定的构建过程。