软件项目实训及课程设计指导——如何在Web应用系统中实现Velocity 模板引擎与Struts 框架相互集成的应用实例

1、Velocity Tools 子项目及其中的 VelocityStruts 组件

（1）Velocity Tools是什么

Velocity Tools 是 Velocity 模板引擎的一个子项目，实现将 Velocity模板引擎与J2EE Web开发环境集成的工具包。如下示例图是Apache Velocity模板官方网站中对Velocity Tools的技术特性和主要功能介绍的局部截图。

J2EE Web应用系统的设计和开发人员通过应用Velocity Tools中相关的组件，不仅可以将Velocity 模板引擎应用于普通的J2EE Web应用系统环境中，也还可以与J2EE系统平台中的各种应用框架相互集成，从而也允许将Velocity 模板引擎应用于如Struts和Struts2、Spring等应用框架的环境中。

（2）VelocityStruts 组件

Velocity Tools 子项目中的 VelocityStruts 组件包含集成 Velocity 模板引擎与 Struts 应用框架的所有功能。VelocityStruts 提供了一组专用的 Velocity 模板引擎工具，用于访问 Struts应用框架中专有的资源和 Velocity 模板文件中的信息。其主要的目的就是结合Velocity模板引擎在MVC体系架构的应用系统中的视图层上的优势跟Struts应用框架在MVC体系架构的应用系统中的控制层上的优势。

VelocityStruts组件会在Struts应用框架的Action组件类返回某个actionForward目标对象之后，自动地检测返回的目标资源的类型——如果发现是一个*.jsp页面文件，则它自动调用JSP解析器Jasper并按照传统的JSP页面流程执行，而如果一旦发现它返回的目标资源是一个Velocity 模板引擎的模板*.vm文件，则会自动地调用Velocity模板引擎中的模板解析引擎对其进行处理——也就是让Struts应用框架的forward 最终转向某个*.vm文件。

如下图所示为Velocity官方网站上对VelocityStruts工作原理及请求响应处理流程的功能介绍的页面内容的局部截图。

2、VelocityStruts系统包文件和用于 VelocityStruts 集成的各种工具

由于在Velocity模板引擎系统中没有提供类似于Struts应用框架标签库中的各个功能标签，而替代的方式是采用toolbox.xml定义文件自定义工具类，这些工具类可以直接在Velocity模板引擎的模板页面中使用——因为这些工具类和Struts 应用框架标签的功能类似，但在使用规则上要比Struts应用框架的标签更容易和更灵活。

下图所示为下载的velocity-tools-1.4.zip工具包文件中所包含的各个工具类所在的JAR包文件，主要为三个文件：velocity-tools-generic-1.4.jar、velocity-tools-1.4.jar和velocity-tools-view-1.4.jar。在将Velocity 与Struts 应用框架相互集成时，应该要将它们加入到Web系统的WEB-INF/lib目录中。

下表所示为Velocity Tools 子项目中的主要的工具类的功能说明，这些工具不仅保留了Struts 框架标签的方便特性，而且还具有Velocity模板引擎的灵活性。从而可以在模板页面中达到与采用Struts框架标签库的标签相同的应用功能效果。

由于本文的篇幅有效，读者如果在开发中需要详细学习和了解这些工具类的功能说明，可以浏览Velocity模板引擎官方网站上对相关工具类的技术介绍资料（参看如下示图所示）。

3、VelocityStruts工具箱配置文件toolbox.xml

J2EE Web应用系统的开发人员可以在VelocityStruts工具箱配置文件toolbox.xml中定义在Web项目中所需要的与Velocity模板引擎配合使用的各种实用工具类，在Velocity 模板引擎系统中提供了许多预先构建好的工具、并且还创建了许多Struts 应用相关的工具来模拟Struts框架中的标签功能。

如下代码示例中的示例为某项目中定义的toolbox.xml文件中的示例内容，并且该文件放在WEB-INF文件目录中。这些工具类的主要功能请读者参考上面表中的功能说明，Web应用系统的开发人员可以根据Web项目中的需要有选择地定义有关的工具类——某Web项目中定义的toolbox.xml文件中的示例内容

<?xml version="1.0"?>
<toolbox>
    <tool>
          <key>link</key>
          <scope>request</scope>
          <class>org.apache.velocity.tools.struts.StrutsLinkTool</class>
    </tool>
    <tool>
          <key>msg</key>
          <scope>request</scope>
          <class>org.apache.velocity.tools.struts.MessageTool</class>
    </tool>
    <tool>
          <key>errors</key>
          <scope>request</scope>
          <class>org.apache.velocity.tools.struts.ErrorsTool</class>
    </tool>
    <tool>
          <key>form</key>
          <scope>request</scope>
          <class>org.apache.velocity.tools.struts.FormTool</class>
    </tool>
    <tool>
          <key>tiles</key>
          <scope>request</scope>
          <class>org.apache.velocity.tools.struts.TilesTool</class>
    </tool>
    <tool>
          <key>validator</key>
          <scope>request</scope>
          <class>org.apache.velocity.tools.struts.ValidatorTool</class>
    </tool>
</toolbox>

4、在web.xml 文件中配置 VelocityViewServlet组件以处理模板文件

由于VelocityStruts是通过一个名为VelocityViewServlet的Servlet组件实现将所有的请求以*.vm为结尾的资源都转交给这个Servlet组件去处理。因此，需要在Web项目的部署描述符web.xml 文件中配置定义出VelocityViewServlet 以处理项目中的各种*.vm 文件、并且告诉 VelocityViewServlet在哪里可以找到toolbox.xml的定义配置文件——请见下面的代码示例中所示的在web.xml文件中对VelocityViewServlet的配置定义内容示例——在web.xml文件中对VelocityViewServlet的配置定义内容示例

<servlet>
      <servlet-name>velocity</servlet-name>
			<servlet-class>org.apache.velocity.tools.view.servlet.VelocityViewServlet</servlet-class>
      <init-param>
            <param-name>org.apache.velocity.toolbox</param-name>
            <param-value>/WEB-INF/toolbox.xml</param-value>
      </init-param>
      <init-param>
            <param-name>org.apache.velocity.properties</param-name>
            <param-value>/WEB-INF/velocity.properties</param-value>
      </init-param>
      <load-on-startup>10</load-on-startup>
</servlet>
<servlet-mapping>
      <servlet-name>velocity</servlet-name>
      <url-pattern>*.vm</url-pattern>
</servlet-mapping>

该VelocityViewServlet的一个初始化参数"org.apache.velocity.toolbox"的含义是在系统中引入了一个工具箱配置文件toolbox.xml，而另一个初始化参数org.apache.velocity.properties定义了Velocity的属性配置文件的位置，这个velocity.properties属性文件定义了Velocity的一些配置信息——读者可以参考前面的代码示例中的velocity.properties属性配置文件的示例。

通过对VelocityViewServlet的配置定义达到把以 *.vm 结尾的文件发送给 VelocityViewServlet，而VelocityViewServlet把Velocity模板引擎的命令处理结果表示成HTML响应输出。

Struts应用框架的控制器把视图转发给VelocityViewServlet组件，而VelocityViewServlet组件在向客户端浏览器发送最终的响应结果之前处理目标*.vm资源文件。

VelocityViewServlet组件提供了对请求对象和属性、会话对象和属性以及 Servlet 上下文和属性的直接访问。但在应用它时，Web应用系统的开发人员要保证在WEB-INF/lib目录下必须要有Velocity模板引擎的velocity-tools-view-1.4.jar系统包文件（请见前面示图中所示系统包目录及文件截图）。

5、编程Action类和在struts-config.xml配置文件中定义Action类

（1）编程实现特定功能的Action类程序

下面的代码示例中所示的UserLoginAction类主要识别用户请求提交的参数是否为合法的值，如果正确则转发到名称为loginSuccess的目标资源中，否则将转发到名称为loginFailure的目标资源中、并产生出错误信息——实现用户登陆功能请求处理的UserLoginAction类代码示例。

package com.px1987.velocitystrutsweb.action;
import org.apache.struts.validator.*;
import org.apache.struts.action.*;
import javax.servlet.http.*;
public class UserLoginAction extends Action {
      public ActionForward execute(ActionMapping actionMapping,
      ActionForm actionForm, HttpServletRequest request,
      HttpServletResponse response) {
            DynaValidatorForm dynaValidatorForm = (DynaValidatorForm) actionForm;
            String userName = (String) dynaValidatorForm.get("userName");
            String userPassWord = (String) dynaValidatorForm.get("userPassWord");
            boolean okOrNot=userName.equals("yang")&&userPassWord.equals("1234");
            if(okOrNot){
                  UserInfo oneUserInfo=new UserInfo();
                  oneUserInfo.setUserName(userName);
                  oneUserInfo.setUserPassWord(userPassWord);
                  request.setAttribute("oneUserInfo", oneUserInfo);
                  return actionMapping.findForward("loginSuccess") ;
            }
            else{
                  ActionErrors errors = new ActionErrors();
                  errors.add(ActionErrors.GLOBAL_ERROR, new ActionError("login.failure"));
                  saveErrors(request, errors);
                  return actionMapping.findForward("loginFailure") ;
            }
      }
}

（2）在struts-config.xml配置文件中定义该Action类及其<forward>的配置

根据Struts应用框架的要求，需要对上面代码示例中的UserLoginAction类在struts-config.xml配置文件中定义该Action类及其<forward>的配置。

表面看起来增加了配置工作量，但实际上并不复杂，仅仅是需要把转发的目标资源从原来的*.jsp页面文件改换成*.vm的Velocity模板引擎的模板文件。

下面的代码示例为UserLoginAction类的定义内容示例，其中定义了名称为loginSuccess的目标资源文件为/userManager/LoginSuccess.vm，而名称为loginFailure的目标资源文件为/userLogin.vm——在struts-config.xml文件中定义UserLoginAction类及其<forward>的配置。

<action input="/userLogin.vm" name="userLoginForm" path="/doUserLogin"
scope="request" validate="false"
type=" com.px1987.velocitystrutsweb.action.UserLoginAction" >
      <forward name="loginSuccess" path="/userManager/LoginSuccess.vm"/>
      <forward name="loginFailure" path="/userLogin.vm"/>
</action>

6、在Web项目中设计和开发实现Velocity 模板文件

（1）userLogin.vm模板文件的内容

userLogin.vm模板文件一方面作为用户登陆请求的功能页面，另一方面也作为登陆失败时的错误信息显示的功能页面，并且在该Velocity 模板文件的页面中利用VelocityStruts的工具类动态地获得所需要的数据——请参考如下代码示例中的Velocity 模板文件的示例—— 实现用户登陆功能的Velocity 模板文件userLogin.vm的示例，并请注意其中黑体所标识的代码语句。

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
      <head>
            <meta http-equiv="Content-Type" content="text/html; charset=gb2312">
            <title>用户登录请求功能页面</title>
      </head>
      <body>
            <form method="POST" action="$link.setAction('/doUserLogin')">
                  请输入用户名称：<input type="text" name="userName"><br>
                  请输入用户密码：<input type="password" name="userPassWord"><br>
                  <input type="submit" value="提交" name="submit">
                  <input type="reset" value="重来" name="reset">
                  #if ($errors.exist())
                  <ul>
                  #foreach ($oneError in $errors.all)
                  <li>$oneError</li>
                  #end
                  </ul>
                  #end
      		 </form>
      </body>
</html>

在userLogin.vm 模板文件中采用$!errors.all 得到错误消息队列中的所有的错误消息，而采用$link.setAction('/doUserLogin ') 获得UserLoginAction类转发的 URL。

由于Velocity模板引擎系统采用简单而强大的模板语言VTL实现对Web页面的渲染，因此能保证在Dreamwaver之类的Web页面可视化编辑器中都能够正常显示（参看如下示例图所示）。

另外，模板文件可以是任意的文件扩展名，采用*.vm、*.html或者*.xml都是可以的（本示例采用*.vm文件扩展名），这样就能直接在Web浏览器中看到Web页面的预览的效果。

（2）LoginSuccess.vm模板文件的内容

该LoginSuccess.vm模板文件作为用户登陆成功后的信息显示页面，并且在该模板文件中动态地获得由前面代码示例中的UserLoginAction类转发来的参数——请参考如下的代码示例中的Velocity 模板文件的示例——用户登陆成功后的信息显示页面LoginSuccess.vm模板文件的内容，并请注意其中黑体所标识的代码语句。

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
    <meta http-equiv="Content-Type" content="text/html; charset=gb2312">
    <title>用户登录成功信息显示页面</title>
    </head>
    <body>
        <b>用户名称为：</b>$oneUserInfo.userName<br>
        <b>用户密码为：</b>$oneUserInfo.userPassWord<br>
    </body>
</html>

如何在J2EE平台开发基于Velocity模板的Web应用

如何在Web应用系统表示层开发中应用Velocity模板技术

如何应用“XML+XSLT”技术分离Web表示层数据和样式

如何应用CSS+Div分离Web表示层数据处理逻辑和展现逻辑

应用XML+XSLT技术分离Web应用表示层数据和样式的实例