"地瓜哥"博客网

博客又有一段时间没有更新了。前一段时间（好几个月前了，哈哈），看一个朋友的博客，内容有长有短，类似日志；最近看一个微信公众号，座右铭是：宁可十年不将军，不可一日不拱卒。所以，考虑以后把每天有趣或者有意义的东西做个小结，记录发文出来。本文章就算是第一个篇文章吧。

公司项目里使用 Velocity 。网上相关的资料很零散，相关的配置查起来挺麻烦了。而且又没有很好的示例，今天又要费心地配置 Toolbox 。所以，干脆记录下来，

工具类配置文件的位置

默认的 Velocity 工具相关的配置放在 WEB-INF/toolbox.xml。当然，也可以在 web.xml 中配置，配置片段如下：

<!-- Define Velocity template compiler -->
<servlet>
  <servlet-name>velocity</servlet-name>
  <servlet-class>
    org.apache.velocity.tools.view.servlet.VelocityViewServlet
  </servlet-class>

  <!--
    Unless you plan to put your toolbox.xml and velocity.properties
    under different folders or give them different names, then these
    two init-params are unnecessary as of VelocityTools 1.3.  The
    VelocityViewServlet will automatically look for these files in
    the following locations.
  -->
  <init-param>
    <param-name>org.apache.velocity.toolbox</param-name>
    <param-value>/WEB-INF/toolbox.xml</param-value>  <!--1-->
  </init-param>

  <init-param>
    <param-name>org.apache.velocity.properties</param-name>
    <param-value>/WEB-INF/velocity.properties</param-value>
  </init-param>
</servlet>

<!-- Map *.vm files to Velocity -->
<servlet-mapping>
  <servlet-name>velocity</servlet-name>
  <url-pattern>*.vm</url-pattern>
</servlet-mapping>

1. 这里就是 Toolbox 的配置路径。

如果使用 Spring MVC，也可以在 Spring MVC 的配置文件中，配置片段如下：

<bean id="velocityConfigurer" class="org.springframework.web.servlet.view.velocity.VelocityConfigurer">
    <property name="resourceLoaderPath" value="WEB-INF/velocity/"/>
    <property name="velocityProperties">
        <props>
            <prop key="directive.foreach.counter.name">loopCounter</prop>
            <prop key="directive.foreach.counter.initial.value">0</prop>
            <prop key="input.encoding">UTF-8</prop>
            <prop key="output.encoding">UTF-8</prop>
        </props>
    </property>
</bean>

<bean id="velocityViewResolver" class="org.springframework.web.servlet.view.velocity.VelocityViewResolver"
      p:order="1">
    <property name="suffix" value=".vm"/>
    <property name="contentType" value="text/html;charset=UTF-8"/>
    <property name="exposeSessionAttributes" value="true"/>
    <property name="dateToolAttribute" value="dateTool"/>  <!--1-->
    <property name="numberToolAttribute" value="numberTool"/> <!--2-->
    <property name="toolboxConfigLocation" value="/WEB-INF/velocity/toolbox.xml"/> <!--3-->
    <property name="allowSessionOverride" value="true"/>
</bean>

1. 问题一。下面在 悬而未决的问题 中说明。
2. 问题二。下面在 悬而未决的问题 中说明。
3. 这里就是 Toolbox 的配置路径。

内置常用工具配置

Velocity 中内置了一些常用的工具类。所有的工具类都在 org.apache.velocity.tools.generic包中。常用的工具类有 MathTool 、 NumberTool 、 DateTool 和 `ListTool`等。可以将这些工具类配置的到上文提到的配置文件中。具体配置如下：

<toolbox>
    <tool>
        <key>mathTool</key>
        <scope>application</scope> <!--1-->
        <class>org.apache.velocity.tools.generic.MathTool</class>
    </tool>
    <tool>
        <key>numberTool</key>
        <scope>application</scope>
        <class>org.apache.velocity.tools.generic.NumberTool</class>
        <parameter name="format" value="#0.00"/> <!--2-->
        <parameter name="locale" value="zh_CN"/> <!--3-->
    </tool>
    <tool>
        <key>dateTool</key>
        <scope>application</scope>
        <class>org.apache.velocity.tools.generic.DateTool</class>
        <parameter name="format" value="yyyy/MM/dd HH:mm:ss"/> <!--2-->
        <parameter name="locale" value="zh_CN"/> <!--3-->
        <parameter name="timezone" value="Asia/Shanghai"/> <!--4-->
    </tool>
    <tool>
        <key>listTool</key>
        <scope>application</scope>
        <class>org.apache.velocity.tools.generic.ListTool</class>
    </tool>
</toolbox>

1. 作用域范围。下面专门来讲解。
2. 默认格式。
3. 本地化样式。
4. 时区。查看 Velocity 的源代码可以获知，这里配置时区 ID即可。下面 常见问题 章节给出获取方法。

这些工具类中的常用方法，大家请查阅相关 Java 代码就能一目了然。这里就不再赘述了。这里简单说明一下配置默认数字样式和默认日期格式化的便利。经过上面配置，在 Velocity 的模板中使用就非常方便了。举几个例来说明一下：

• 如果需要格式化货币，可以直接写成 $numberTool.currency($order.fee)， 输出结果会自动两位小数，前面还会加上软妹币的标识符 ￥；

• 如果需要格式化日期，则可以 $dateTool.format($order.createTime)，输出结果则是：
  2016/02/16 22:47:26。

• 如果需要判断列表是否为空，则可以： $listTool.isEmpty($orderList)。

是不是非常方便？

工具作用域说明

上面的配置中，有作用域一项，配置文件中，只有 application`一种。其实，一共 `request,session 和 application 三种。

对于 request 还可以设定有效 URL。示例如下：

<tool>
   <key>catalog</key>
   <scope>request</scope>
   <request-path>/catalog/*</request-path>
   <class>com.diguage.tools.CatalogTool</class>
</tool>

这里再多说一句，根据上面的示例也可以看出，可以将自己开发的工具类也配置到这里，进一步扩展Velocity 的功能。

其他配置

在配置文件中，还可以给工具类配置参数，可以配置常量。D瓜哥用的不多，就不再给示例了。可以在给出的参考资料中来查询。

悬而未决的问题

如何获取经过配置的工具类对象？

由于项目中使用“分”作为货币单位。所以，在展示时需要先除以100转化成元再展示。直接使用 Velocity 所以，想自定义一个工具类，将这个转化过程在内部实现，在模板中简写成 $currencyTool.currency($$order.fee)。但是，总是报错，甚是麻烦。废话少说，直接上代码吧（略去了在 toolbox.xml 的配置）：

package com.diguage.util.view;

import com.diguage.util.GlobalConstants;
import org.apache.velocity.VelocityContext;
import org.apache.velocity.tools.ToolManager;
import org.apache.velocity.tools.config.DefaultKey;
import org.apache.velocity.tools.generic.MathTool;
import org.apache.velocity.tools.generic.NumberTool;

/**
 * 货币格式化工具类
 *
 * @author D瓜哥, http://www.diguage.com/
 * @since 2016/2/16.
 *
 * TODO 怎样在自己的类中利用Velocity的NumberTool，需要获取项目中根据配置文件初始化好的NumberTool对象？（这样就不需要配置样式了）
 */
@DefaultKey("currency")
public class CurrencyTool {
    private NumberTool numberTool;
    private MathTool mathTool;

    private ToolManager velocityToolManager;

    public CurrencyTool() {
        velocityToolManager = new ToolManager();
        velocityToolManager.configure("/WEB-INF/velocity/toolbox.xml");  // -1-
        VelocityContext context = new VelocityContext(velocityToolManager.createContext());
        numberTool = (NumberTool) context.get("numberTool");
        mathTool = (MathTool) context.get("mathTool");
    }

    public String currency(Object original) {
    }
}

1. 这就是找不到的配置文件

报错信息是找不到配置文件。

说一下问题吧。首先，这样写是否可行？其次，配置文件的路径该怎么搞？报错原因，D瓜哥想到一点，这里写的路径是绝对路径，其实是想让它根据 Web 项目的上下文路径来查找。所以，肯定找不到啊。这点，D瓜哥回头再试试怎么搞？如果好的方案，还请赐教。

Spring 配置

上面提到的 问题一 和 问题二，为什么在 Spring MVC 中还需有配置 dateTool 和 numberTool，D瓜哥还没有搞清楚这是干什么。记录下来，留在后续再“追查”这个问题。

获取时区 ID

在 Java 中，如何获取时区 ID？这个问题，以前没有留意过，这里配置所需，查了一下，使用如下代码就可以查看 Java 中所有可用的时区 ID。

/**
 * D瓜哥， http://www.diguage.com
 */
String[] availableIDs = TimeZone.getAvailableIDs();
for (String id : availableIDs) {
    System.out.println(id);
}

参考资料

1. Toolbox Configuration
2. Creating Custom Tools for Apache Velocity