基於Velocity的Web開發指南

    原文名稱《Web Application Guide》，副標題爲基於Web的應用技術和VelocityViewServlet入門，地址爲此處連接。文章分爲四部分，第一部分，通覽使用Velocity建立Web應用的好處，第二部分，講述須要使用的具體框架，第三部分，主要探討使用Velocity時的問題，第四部分，講解一個入門實例。

使用Velocity建立Web應用

    Velocity一般被用來生成web頁面，能夠直接替代JSP，如下是使用Velocity的好處：

1. 簡單 - 不懂技術的網頁設計者能夠直接使用和維護。
2. 易於維護 - 不包含腳本語言？
3. 直接訪問方法和屬性 - 網頁設計者也能夠訪問對象的方法和屬性。
4. 一致性 - Velocity不只能夠生成網頁，也能夠完成其餘文本生成任務（如郵件發送）。

配合使用的具體框架

    Velocity引擎的主要目的僅僅是爲了生成文本，並且在模板基礎上生成。所以，Velocity本身不包含任何web相關的功能，因此，咱們仍是須要一個框架來響應HTTP請求、來處理用戶認證、來造成業務邏輯調用、以致造成響應，如下列出幾個好的選擇：

    1. Velocity工具之一：VelocityViewServlet（Velocity視圖服務器小程序） - 最簡單的開始使用 Velocity的方法是下載 Velocity Tools 並使用 VelocityViewServlet。這個服務器端小程序很是容易配置和安裝。方法以下：服務器目錄下建立模板文件夾-->編輯XML文件列上各類「工具」（放在頁面中的）-->完工。

    2. Velocity 工具之二：VelocityStruts （Velocity支撐程序）-- 咱們可能比較熟悉流行的 Struts 框架，它原來是設計爲JSP提供豐富功能的。而使用 VelocityStruts，你就可讓 Velocity 徹底替代 JSP啦，VelocityStruts可讓你充分利用 Struts框架的優點。

    3. 第三方框架 -- 在Wiki頁面還列出了不少第三方框架，查看  PoweredByVelocity  頁面。其中，Spring 多是最知名的一個。Apache Turbine 也有不少特點且用處不小，Turbine 將 Velocity 做爲主要的頁面語言，Turbine 自己就是那些開發 Velocity 的程序員建立的。更爲簡單的框架還包括 Click 或者 Maverick ，他們提供了簡單的控制器框架，能與Velocity完美整合。

    4. 本身動手 -- 咱們還能夠本身建立框架。咱們能夠建立小程序來調度、從文件或數據庫獲取模板、整合業務邏輯併發送結果給用戶。一般，從現有的框架開始進一步修改它是個不錯的選擇。特別的，你能夠經過建立子類的方式向 VelocityViewServlet 添加新的功能。

    最後聲明，VelocityServlet 不再會被維護，而被 VelocityViewServlet  替代。

Web相關棘手問題

    Web應用開發涉及到不少問題，如下列出一些最常遇到的：

使人頭疼的資源載入問題

默認的 Velocity 引擎設置中使用 FileResourceLoader，這個配置對於那些不使用 servlet 引擎的應用來是很棒的。但一旦你決定使用 war 文件部署web應用，那麼 FileResourceLoader 可能成爲你的敵人。因此，咱們明確建議你不要使用 FileResourceLoader。

事實上，還有不少 ResourceLoader 實現，但這些 ResourceLoader 在和 Velocity引擎配合使用時將要求咱們將模板存放在標準文件系統以外（如classpath、數據庫、遠程服務器等）。咱們說，若是運行起來，那很好。但咱們認可對大多數來講，這個部署方式很不方便。

最簡單的替代方案實際已經存在於 VelocityTools 中，即 WebappResourceLoader，這個 ResourceLoader 是特別設計來像FileResourceLoader同樣工做的，但 WebappResourceLoader 知道 servlet 上下文，容許咱們配置servlet root 相關的資源路徑，而不是本地文件系統。

若是你正使用 VelocityViewServlet，那麼 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/

下一步在初始化引擎時，你也須要把 ServletContext 放入 Velocity引擎的應用屬性中，這使得 WebappResourceLoader 知道如何找到模板。

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

改變對象狀態？--不要！

Velocity 提供了以引用方式調用對象方法的能力，這在頁面上顯示信息時頗有用，但當對象或應用狀態改變時卻很危險。

例如，下面的代碼安全地調用了 列表的 size() 方法，用以顯示結果：

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

而不安全的例子以下面的，一個財務頁面，存在一個對象，逐年計算數據。calculateNextYear()方法用於計算下一年數據，並提升內部計數器。

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

這一方法的問題在於 此段代碼不能在當前頁面中重複使用。你可能也不想這樣作，但你很容易忘記，特別是當你須要剪切、複製控制語句時（如 #if 或者 #foreach），這在處理應用或會話層狀態時所帶來不少問題。

咱們建議的實踐方式是僅使用 Velocity 顯示信息，方法的調用僅用於獲取信息，而不要改變對象狀態，由於這樣改變對象或應用狀態很危險。

若是你以爲你確實須要改變對象狀態，嘗試在控制器中計算所須要的值，而後將他們放進 List或Map中，記住使用控制器。

另外，補充一點，你應該習慣將 List 或 Set 放入頁面上下文，而不要使用 Iterator 或 Enumeration，這很明顯，List 或 Set能夠被屢次使用，而 另外兩個卻不行。

HTML/XML實體轉義

用戶輸入的文本中可能包含 HTML或XML實體，如 < > &，這些須要提交時被轉義。這是必須的，由於要保證文本能夠被正確顯示，同時爲阻止跨站腳本攻擊。哦。。。。不像 JSTL，Velocity默認不提供轉義。。。。

而後，Velocity 提供了 ReferenceInsertionEventHandler 來處理這個問題。你能夠配置 EscapeHtmlReference 處理器進到 velocity.properties 文件，以正則表達式方式指定匹配內容。下面的例子將轉義 以 msg開頭的HTML實體，如 $msgText。

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

注意：其餘的轉義有時也是必須的，好比在樣式表中 @ 字符須要被轉義，JS字符串中單引號也須要轉義。

加強應用安全

由於 web應用運行在服務器上，擁有不少用戶和須要保密的資源，所以必須增強應用安全。Velocity引入了安全機制。具體見《 Building Secure Applications with Velocity 》（涉及系統配置、跨站腳本、方法自省）。另外，你能夠指定 SecureUberspector 來防止頁面設計者犯錯誤。

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

日誌文件

A minor point is that (in some circumstances) Velocity, in the absence of any log-related configuration, creates a log file in the current directory. When Velocity is used in a web application the "current directory" is usually the current directory from which the application server is started. If you start seeing the file "velocity.log" files in random places on your server filesystem, check the Velocity log configuration. This is due to the default use of the Avalon Log Kit when present in the classpath. Typically this occurs when Velocity is used within a web application outside of web page generation (e.g. for sending email). To solve this problem, remove any file labeled "avalon-logkit" from the classpath or properly configure the log file location.

最後一小點，Velocity 在沒有任何日誌配置時，會在當前文件夾建立日誌文件。當前文件夾通常是應用服務器啓動時的目錄。

入門實例

下面是使用 VelocityViewServlet 建立 web應用的入門實例。注意：咱們建議您從源代碼編譯 VelocityViewServlet。而實際上，這不是必須的，咱們推薦這樣只是爲了讓咱們有機會查看源代碼並隨後編譯例子文件。

前提包括安裝 JDK 和  Apache Ant.

瞭解更多，請參考 Velocity Tools  文檔。

1. 下載 Velocity Tools 項目源代碼（特別是他包含例子代碼），地址:download page
2. 編譯 Velocity Tools jar，編譯 simple例子:

   ant example.simple

3. 查看 examples 文件夾，你會找到 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 文件到這個文件夾中。在 examples/WEB-INF 中，你會看到文件 tools.xml。這個文件指定了 一個 Tools 列表，這些自動配置：

   <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>

4. 拷貝這個文件夾到 咱們的Tomcat服務器的 webapps文件夾；咱們也能夠拷貝 simple.war 文件。這樣你就能夠訪問這個單頁面應用了，以下：

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

5. 增長新的頁面，進一步體驗吧。注意：訪問不一樣頁面能夠經過改變URL地址來實現。進一步查看 Velocity Tools 文檔。