[翻译]使用 Velocity 构建一个web应用

做为JSP的替代方案，Velocity 常常被用来在应用中生成web页面。使用Velocity生成页面的一些好处有：

Simplicity - 页面能够被非技术型的web设计师创做和维护了。

Ease of maintainance – 脚本代码能够像MVC模式所要求的那样从web页面中移除了。

Access both methods and properties - web设计师能够在一个Context中引用方法和属性对象了。

Consistency - Velocity可以被用来执行其余类型的文本生成任务（好比发送邮件），从而提供一种一致的文本信息格式配置。

本文档提供一些关于在web应用中使用Velocity的入门信息。

 

使用一个框架

原始的使用Velocity引擎的目标是根据模板生成文本。因此Velocity中自己并无包含任何和web相关的功能。为了让一个web应用起做用，你须要一个框架去回应HTTP请求、控制用户认证、调用业务逻辑，而后生成响应。下面是一些强大的竞争者。

一、Velocity Tools / VelocityViewServlet - 入门最简单的办法是下载相关 Velocity Tools 子项目，使用里面的VelocityViewServlet。 配置和安装这个servlet是容易的。在你的web服务器上面建立一个放模板文件的文件夹，选择性的XML文件，里面列出须要放入Context中的各类“工具”，就好了。更多的详细内容能够在下面的教程中找到。

二、Velocity Tools / VelocityStruts - 你也许知道原生的，被设计用来知足JSP应用功能需求的Struts框架。Velocity 的 VelocityStruts 模块能够代替JSP，使用Velocity 做为模板语言。这样就可让你使用Velocity设计页面的时候能够大量的利用Struts的基础设施。

三、Third party frameworks – 已经有许多的第三方框架被列在 PoweredByVelocity wiki页面中。其中， Spring 多是最繁茂和知名的。 Apache Turbine 有许多的特性也颇有用。 它被构建的时候把Velocity做为基础的页面语言，这没有什么好惊讶的，由于许多的Velocity的开发者都参与了它的构建。 更加简单的选择有 Click 和 Maverick 框架， 它们提供了简单的，同Velocity集成良好的控制器结构。

四、Build your own - 最后的一个选择是去构建你本身的框架。 建立一个dispatcher servlet, 从文件系统或者数据库中抽取模板，加入你的业务逻辑数据，而后把结果发送给用户。 在已有的框架基础上定制，经常可让你更加的节约时间。通常状况下，你能够经过建立一个VelocityViewServlet的子类添加新的功能。

另外，你可能偶然引用了 VelocityServlet 类， 它从版本1.4版本就被包含在 Velocity Engine 模块中，如今不建议使用了。 VelociyServlet 不会再被维护了，咱们强烈建议你使用Velocity Tools中的VelocityViewServlet类。

 

Web特有的问题

web应用上的Velocity有一些特有的问题。下面是就一些最多见的问题的简要讨论。

使人头痛的资源加载

Velocity 设置默认使用 FileResourceLoader。 在没有被部署在servlet引擎中这样仍是蛮好的。一旦你须要构建一个web应用，而且把这个应用发行或者部署成一个war文件，FileResourceLoader 就会成为你最大的敌人。因此，咱们明确的建议你不要在你的web应用中使用 FileResourceLoader 。

真的，任何其余外部实现的 ResourceLoader 都行， 可是其余由Velocity Engine发布的 ResourceLoader 都须要你把你的模板文件存储在除了标准的文件系统之外的某个地方（好比：classpath、数据局，或者远程服务器）。若是那样对你是适用的，那就很棒了！然而，咱们也要指出这些并不适合全部人的开发周期中的需求。

FileResourceLoader 最简单的替代事实上是 VelocityTool 计划的一部分。 它是 WebAppResourceLoader。 这个ResourceLoader像FileResourceLoader同样起做用，可是它知道servlet context，容许你配置servelt根路径下的资源路径，而不是本地的文件系统。

若是你正在使用VelocityViewServlet， 它能够自动配置而且准备好使用WebAppResourceLoader了。 所以，若是你想改变配置的路径， 你须要作的只是在你的 velocity.properties 文件中加上下面这样一行：

webapp.resource.loader.path=/WEB-INF/mytemplates/

若是你须要设置使用你本身实现的WebAppResourceLoader， 你像下面这样作配置：

resource.loader=webapp
webapp.resource.loader.class=org.apache.velocity.tools.view.WebappResourceLoader
webapp.resource.loader.path=/WEB-INF/mytemplates/

在你本身的 VelocityEngine 初始化以前，你也可能须要把 ServletContext 放入你本身的 VelocityEngine 属性中。这样就可让 WebAppResourceLoader 知道如何去寻找到模板文件。

myVelocityEngine.setApplicationAttribute("javax.servlet.ServletContext", servletContext);

 

不要改变对象的状态

Velocity 提供调用一个对象的任何方法的能力，就像一个对象引用那样。这在须要在页面中展现信息的时候是颇有用的，可是若是调用方法使对象或者应用的状态发生了变化，将会是很危险的。

好比，下面这个方法安全的调用了一个list 的 size方法展现结果。

There are $users.size() currently logged in.

一个不安全的方法，在context中操做一个与财务页面相关的对象，使数据一年一年的计算。这个calculateNextYear 方法计算下一年的数据，访问一个内部的计数器。

2005 data: $table.data
$table.calculateNextYear()
2006 data: $table.data

这种方式的问题是这段代码不能在页面的多个部分被重复。你可能不会想要这样去作，可是在剪切和粘贴代码或者编写控制结构（好比 #if 或者 #foreach）的时候很容易遗忘这一点。

这里（强烈的）建议的实践是仅仅使用 Velocity 与在文本中插入信息的场景。对于获取信息而言，调用方法是颇有用的。而通常经过在模板文件中调用一个方法去改变对象的状态倒是一个坏主意，使用这种方式去改变应用的状态永远都是个坏主意。

若是你发现本身须要去改变对象的状态（就像上面那种状况）,尝试在控制器模块中去提早计算好全部可能的值，而后把它们放入一个List或者Map数据结构中。全部对应用状态的改变都应该在控制器模块中作完。

须要提到相关的一点，你应该经常把一个List或者Set对象放入context环境中，而不是一个Iterator或者Emumeration对象。这样就运行这样的集合对象能够被屡次使用，而不会改变其行为属性。

 

避免 HTML/XML 实体

全部用户输入的包含特殊的 HTML 或者 XML 实体（好比 < , > 或者）的文本，都应该在包含进web页面以前被避免掉。 这是必须的，以确保文本可见，同时防止危险的 cross-site scripting （XSS，一种安全隐患）。不像好比JSTL（the Java Standard Tag Language found in Java Server Page）那样，Velocity默认不会去避免这些引用。

而后（万幸的是），Velocity经过提供一个ReferenceInsertionEventHandler 对象——它能够在被插入页面以前改变应用的值——来提供这种能力。有点特别的是，你可以同坐在你的 velocity.properties 文件中配置匹配一个正则表达式（可选的方式）来避免全部的这种实体引用。下面的这个例子将避免掉任何以“msg”开头的应用中的HTML实体（e.g. $mgsText）。\

eventhandler.referenceinsertion.class = org.apache.velocity.app.event.implement.EscapeHtmlReference
eventhandler.escape.html.match = /msg.*/

并非说其余种类的避免有时候可能被用到。好比，在样式表中 @ 字符是须要被避免掉的，在 Javascript 字符串中单引号是该被避免掉的。

 

确保应用的安全

因为一个web应用是运行在一个中央服务器中的，那样一般会有多个用户和机密的资源，于是须要注意确保这个web应用时安全的。大部分适用于web应用的安全原则都已经构建于Velocity了。一些特殊的问题（好比系统配置，大可能是 cross-site scripting和方法的内调）已经被 Building Secure Application with Velocity 这篇文章中被写到了。通常状况下，你可能想要阻止模板设计人员去包含“危险”的反射相关的方法，这时能够制定SecureUberSpector对象去 get/set 属性，执行方法调用。

runtime.introspector.uberspect = org.apache.velocity.util.introspection.SecureUberspector

 

日志文件

一个小的要点（在一些状况下）是，不用任何跟日志相关的配置 , Velocity 在当前路径下建立了一个日志文件。当 Velocity 被使用于一个web应用中时，当前路径经常在于应用服务的启动之处。若是你在你的服务器文件系统随机的什么地方开始查看“velocity.log”文件， 那就去检查 Velocity 日志配置。这归因于使用了置于你 classpath 中时的 Avalon Log Kit。典型的是， Velocity 用于一个web应用中，除了web页面生成的状况（好比：为了发送邮件）。为了解决这个问题，那就移除掉任何classpath或者property配置文件中的标有”avalon-logkit“，以控制日志文件位置的配置。

 

教程

接下来是一个使用 VelocityViewServlet 构建一个简单的web app的简明教程。

这里建议你从源代码编译 VelocityViewServlet。这并非实际使用 VelocityViewServlet 须要作的，咱们这样建议是为了能看到源代码，而后去编译实例文件的这种状况。

以下操做的前置条件是 JDK 和 Apache Ant。

一、从下载页面下载 Velocity Tools 项目源代码（你须要的实例的源代码）。

二、构建Velocity Tools jar文件和”simple“实例，经过敲入：

ant example.simple

三、看一看”simple“实例的目录。你将会看到一个”index.vm“文件，这里是其中内容的摘录：

<html>
<body>
I'm a velocity template.

#if( $XHTML )
  #set( $br = "<br />" )
#else
  #set( $br = "<br>" )
#end

$br
$br

Here we use a custom tool: $toytool.message

$br
$br

Here we get the date from the DateTool:  $date.medium
</body>
</html>

你能够复制任何新加的velocity文件到相同的这个目录中。 在 example/WEB-INF 中，你会看到一个”tools.xml”文件。它包含了一个自动引入到context环境中的“工具”列表。

<tools>
    <data type="boolean" key="xhtml" value="true"/>
    <data type="boolean" key="isSimple" value="true"/>
    <data type="number" key="version" value="2.0"/>
    <data key="foo">this is foo</data>
    <data key="bar">this is bar.</data>
    <toolbox scope="request">
        <tool key="toytool" class="ToyTool" restrictTo="index*"/>
    </toolbox>
    <toolbox scope="session">
        <tool key="map" class="java.util.HashMap"/>
    </toolbox>
</tools>

最后在web.xml文件中指定servlet的名字和toolbox.properties文件的位置。

<web-app>
  <servlet>
    <servlet-name>velocity</servlet-name>
    <servlet-class>org.apache.velocity.tools.view.VelocityViewServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>velocity</servlet-name>
    <url-pattern>*.vm</url-pattern>
  </servlet-mapping>
  <welcome-file-list>
    <welcome-file>index.vm</welcome-file>
  </welcome-file-list>
</web-app>

四、把这个目录复制到你Tomcat下的webapps目录中。你也能够复制simple.war文件，可是复制整个目录可让你尝试变化。你可经过这个（或者相似的）URL访问你的simple单页webapp：

http://localhost:8080/simple/index.vm

五、尝试加入新的Velocity页面。这里你能够访问任何velocity页面，经过改变URL。 尝试改变整个tools.xml的或者建立属于你本身的工具。查阅 Velocity Tools 文档，“showcase”实例应用，和wiki，以获取更多大量的利用工具的信息。

 

----------------------------------------

这里是原文的地址：

http://velocity.apache.org/engine/releases/velocity-1.7/webapps.html

 

 

 

 

 

 

 

 

 

。。。