[翻譯]使用 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

 

 

 

 

 

 

 

 

 

。。。