Apache Velocity Tools 教程

1. 项目目录结构及介绍

Apache Velocity Tools 的源码仓库组织如下：

• generic-tools/: 包含通用工具类，适用于标准Java SE Velocity项目。
• velocity-tools-view/: 提供用于Web应用程序的视图层集成工具，包括 VelocityViewServlet 和 VelocityLayoutServlet。
• velocity-tools-jsp/: 专门用于JEE JSP环境的工具。
• velocity-tools-examples/: 示例项目，包括简单的例子和一个全面展示工具功能的示例Web应用。
• docs/: 文档相关的文件。
• pom.xml: Maven构建配置文件。

每个子目录都有其特定的功能和用途，开发者可以根据需要选择相应的部分进行集成或学习。

2. 项目启动文件介绍

在Apache Velocity Tools中，没有明确的单一启动文件，因为它是作为一个库使用的。通常，你需要在你的Web应用中配置web.xml以启动VelocityViewServlet或VelocityLayoutServlet来处理Velocity模板请求。例如，以下是如何配置VelocityViewServlet的一段web.xml片段：

< servlet >
    < servlet-name >VelocityView</ servlet-name >
    < servlet-class >org.apache.velocity.tools.view.VelocityViewServlet</ servlet-class >
    < init-param >
        <!-- configure your Velocity engine properties here -->
        < param-name >resource.loader</ param-name >
        < param-value >class</ param-value >
    </ init-param >
    <!-- ... other parameters like toolbox.config -->
</ servlet >

< servlet-mapping >
    < servlet-name >VelocityView</ servlet-name >
    < url-pattern >/your-template-extension/*</ url-pattern >
</ servlet-mapping >

这段配置将使所有以/your-template-extension/开头的URL由VelocityViewServlet处理。

3. 项目配置文件介绍

Apache Velocity Tools 使用 toolbox.xml 文件来定义工具箱（Toolbox）中的工具及其配置。这个文件通常位于Web应用的 WEB-INF 目录下，或者可以通过 toolbox-config 初始化参数指定位置。一个基本的toolbox.xml文件可能如下所示：

< toolbox scope="request">
  < tool class="org.apache.velocity.tools.generic.DateTool" />
  < tool class="org.apache.velocity.tools.generic.NumberTool" />
  <!-- ... add other tools as needed -->
</toolbox>

在这个例子中，DateTool 和 NumberTool 将被添加到每个HTTP请求的工具箱中，可供Velocity模板使用。

在Web应用中，可以使用 VelocityContext 来加载配置文件并创建工具箱实例，如下所示：

VelocityEngine ve = new VelocityEngine();
ve.init();

VelocityContext context = new VelocityContext();
ToolboxFactory toolboxFactory = new ToolboxFactory();
toolboxFactory.configure("/WEB-INF/toolbox.xml");
context.put("toolbox", toolboxFactory.getToolbox(request));

这样，模板就可以通过 $toolbox.date.now() 或 $toolbox.number.format 访问已经配置好的工具了。

请注意，实际配置可能会根据项目需求包含更复杂的设置，如定制工具工厂、自定义工具实例等。务必参考项目文档以获取更多详细信息。