用Velocity構建一個Web應用
Velocity在應用中通常用于生成頁面，來直接代替JSP。一些使用Velocity來生成Web頁面的好處如下：Velocity is often used to generate web pages in applications, usually as a direct replacement for JSP. Some of the benefits of using Velocity to generate web pages are:
- 簡單Simplicity -沒有多少技術的Web設計者就能書寫這些頁面。 The pages can be written and maintained by non-technical web designers.
- 容易維護Ease of maintainance - 使用推薦的MVC開發模式，小程序（script）不再出現在Web頁面中。Scripting is removed from web pages with the recommended MVC approach.
- 對方法和屬性的訪問Access both methods and properties - Web設計者可以訪問上下文中一個對象的屬性和方法。Web designers can reference methods as well as properties of objects in a context.
- 一致性Consistency -Velocity可以被用作其他的文本生成工作（比如發送email），并提供了一致的標記語言。 Velocity can be used for other text generation tasks (such as sending email) providing a consistent way to mark up text.
這篇文檔中提供了一些將Velocity用于Web應用中的基本信息。This document provides some basic info on getting started with Velocity in a web application.
使用一個框架
Velocity引擎的主要功能是基于一個模版生成文本。因此，Velocity并沒有包含任何與Web相關的功能。The primary purpose of the Velocity engine is simply to generate text based on a template. Consequently, Velocity does not contain any web-related functionality in and of itself. 要創建一個Web應用，你需要一個框架來響應HTTP請求，處理用戶認證，調用業務邏輯，并且返回響應。To make a web application, you will need a framework to respond to HTTP requests, handle user authentication, make business logic calls, and generate a response. 下面是一些非常強大的提供者。There are several strong contenders.
- Velocity Tools / VelocityViewServlet - 最簡單的開始的方法是下載Velocity Tools子項目，使用VelocityViewServlet。這個servlet的配置和安裝都很簡單。The easiest way to get started is to download the companion Velocity Tools subproject and use the VelocityViewServlet . This servlet is easy to configure and install.你需要在web服務器上創建一個模版的目錄，并編輯一個包含了需要放置在上下文中的"Tools"的列表的XML文件就行了。具體的細節請參見下面的指南。 You create a directory of templates on your web server, edit an XML file that lists various "Tools" to place in the context and you are off. More details can be found in the tutorial below.
- Velocity Tools / VelocityStruts
- 也許你對流行的Struts框架比較熟悉。Struts最開始是為了設計一個為JSP提供更多有用的功能的應用。You may be familiar with the popular Struts framework, originally designed to provide much needed application functionality to JSP.在Velocity Tools 的VelocityStruts模塊的幫助下，你可以用Velocity代替JSP作為頁面的模版語言。這允許你使用Struts強大的基礎設施的好處的同時，使用Velocity設計頁面。 With the VelocityStruts module of Velocity Tools you can substitute Velocity for JSP as the page template language. This allows you to take advantage of the large base of Struts infrastructure while designing pages using Velocity.
- 第三方框架Third party frameworks - 還有許多的第三方框架在PoweredByVelocity wiki 頁面上。There are a number of third party frameworks listed on the PoweredByVelocity wiki page. 在其中，Spring可能是被公認的最先進的框架了。Of these, Spring is probably the most sophisticated and well known. Jakarta Turbine 有許多特點并且也很有用，它基于Velocity并使用Velocity作為主要的頁面語言，這并不奇怪，因為有許多Velocity的早期開發者在開發和維護它。Jakarta Turbine has many features and can also be very useful. It was built with Velocity as the primary page language, which is not surprising since many of the original Velocity developers were involved in creating it.一個更簡單的選擇是Maverick框架，Maverick提供了一個很好的集成了Velocity的簡單的控制器結構，但僅此而已。 A simpler alternative is the Maverick framework which provides a simple Controller architecture that integrates nicely with Velocity but has no bells or whistles.
- 構建你自己的Build your own - 最后的一個選擇是創建你自己的框架。A final alternative is to build your own framework.建立一個轉發servlet（Dispatcher servlet），從一個文件或者數據庫中檢索出模版，集成你自己的商務邏輯，并返回結果給用戶。 Create a dispatcher servlet, retrieve templates from a file or database, integate with your business logic and send the results back to the user. 從一個已有的框架出發并擴展它通常是一更簡單的方法。特別的，你只需要為VelocityViewServlet創建一個子類，既能向其中添加新的功能。Often you'll have an easier time starting with one of the existing frameworks and customizing it. In particular you can add new functionality to the VelocityViewServlet simply by creating a subclass.
順便一提，你可能偶然發現VelocityServlet這個類，該對象是一個在Velocity 1.4版本中不提倡使用的servlet。VelocityServlet已經不再維護，所以，我們強烈建議你使用Velocity Tools中的VelocityViewServlet。As a side note, you may also come across references to VelocityServlet, which is a deprecated servlet that was included in the Velocity Engine up to version 1.4. Since VelocityServlet is no longer being maintained we strongly recommend you use VelocityViewServlet in Velocity Tools instead.
Web方面的問題Web-Specific Issues
對于Velocity在web的應用，有一些問題需要討論。這些都是經常遇到的問題中的一些簡單的討論。There are a few issues with Velocity that are specific to web applications. Here is a brief discussion of the most commonly encountered issues.
不要改變對象的狀態Changing Object State - Don't!
在Velocity中，如果將一個對象作為一個引用，那么Velocity提供了訪問該對象的任何方法的能力。在頁面中顯示信息的時候，這個功能很有用，但是同時如果對象或者應用的狀態被改變了，這樣做也是很危險的。Velocity provides the ability to call any method of an object acting as a reference. This can be useful when displaying information into the page but is dangerous when object or application state is modified.
舉個例子，下面的代碼安全的調用了一個list的size()方法并顯示結果。For example, the following code safely calls the size() method of a list and displays the result.
There are $users.size() currently logged in.
一個不安全調用的例子：在一個財務web頁面上，在上下文中的一個對象能計算每一年的數據。方法calculateNextYear()方法能計算下一年的數據并將一個內部的計數器做增加操作。An example of an unsafe operation concerns a financial web page with an object in the context that calculates data year by year. The method calculateNextYear() calculates data for the next year and advances an internal counter:
2005 data: $table.data
$table.calculateNextYear()
2006 data: $table.data
The problem with this approach is that the code cannot be repeated in multiple parts of the page. You may not intend to do so, but it's easy to forget this when cutting and pasting or writing control statements (such as #if or #foreach). This becomes more of an issue when you are dealing with application or session-level state.
我們強烈建議的實踐是只使用Velocity向文本中插入信息。方法調用會是得到信息的一個有效的方法，但一般說來使用一個方法調用來改變對象的狀態是一個不良的觀念，來改變應用的狀態一定是一個錯誤的想法。The (strongly) recommended practice is to only use Velocity for inserting information into text. Method calls can be useful to retrieve information. However, it's generally a bad idea to use a method call to change object state, and it's always a bad idea to change application state.
如果你必需要改變對象的狀態（比如前面的例子），可以預先計算出所有可能的值并放入一個List或則Map對象中。所有的要改變應用的狀態的動作應該總是放在控制器中。If you find yourself needing to change object state (as in the previous example) try precalculating all the possible values in the controller and putting them in a List or Map. Any changes to application state should always be done by the controller.
一個相關的注意，你應該在上下文對象中放入一個List或者一個Set對象，而不是放入一個Iterator或者Enumeration。這樣允許集合對象在沒有改變時重復使用。On a related note, you should always put a List or Set into the context instead of an Iterator or Enumeration. This allows the collection to be used more than once in the page with no change in behavior.
去掉HTML/XML標記Escaping HTML/XML Entities
任何用戶添加的帶有HTML或者XML標記（比如<,>,&）的文本都應該在填到web頁面之前被去掉。為了確保頁面正確顯示和避免危險的跨站點腳本（cross-site scripting一種攻擊手段，在頁面中包含另一個帶有木馬的頁面）。不象JSTL（Java標準標記語言），Velocity不包含去除HTML標記的功能，但是你可以通過三種方法來達到目的。Any user-entered text that contains special HTML or XML entities (such as <, >, or &) needs to be escaped before included in the web page. This is required, both to ensure the text is visible, and also to prevent dangerous cross-site scripting. Unlike, for example, JSTL (the Java Standard Tag Language found in Java Server Pages), Velocity does not contain any HTML-specific escaping functionality. However, you have three options:
- 創建一個"Tool"，并且包含一個能去掉HTML標記的方法。比如 $escape.html($usertext)。這是最簡單的解決問題的方法。Create a special "Tool" (an object in the context) with a method that performs escaping, for example $escape.html($usertext). This is conceptually the easiest way to solve this problem.
- 創建一個自定義的ReferenceInsertionEventHandler ，能自動的去掉所有引用中的HTML標簽。如果所有的引用中的內容都需要被檢查并去掉HTML標簽，那么這樣做是最省事的。Create a custom ReferenceInsertionEventHandler that automatically escapes every reference. If all references need to be escaped, this is the most painless method.
- 創建一個自定義的標識，比如#escape，來去掉在該標識對里面的所有引用中的HMTL標簽。Create a custom directive (e.g. #escape) that escapes all text within the directive block.
注意，有時候其他的標記也需要被去掉。比如在CSS里面，@需要被去掉，在Javascript，單獨的'符號需要從字符串中去掉或替換。Note that other kinds of escaping are sometimes required. For example, in style sheets the @ character needs to be escaped, and in Javascript strings the single apostrophe ' needs to be escaped.
應用的安全Securing the Application
當一個web應用在服務器上開始運行了，有了若干的用戶和一些受保護的資源，這時候，應用的安全性方面的要求就顯現出來了。Velocity中已經涵蓋了大多數標準的web安全性標準。一些特別的問題（比如系統配置，跨站點腳本，或者方法自省）等都在Building Secure Applications with Velocity 這篇文章上有所介紹。Since a web application is running on a central server, that typically has multiple users and confidential resources, care must be taken to make certain that the web application is secure. Most standard web security principles apply to a web application built with Velocity. A few specific issues (such as system configuration, more on cross-site scripting, and method introspection) are written up in this article on Building Secure Applications with Velocity.
日志文件Log Files
還有一點就是Velocity在日志方面的配置比較缺乏。他總是在當前文件夾中創建一個日志文件。當Velocity用在Web應用中的時候，當前文件夾指的是應用開始的那個文件夾。如果你發現"velocity.log"這個文件出現在你文件系統的不固定位置，請檢查你的Velocity 日志的配置。一般情況下，出現這個問題的原因是在除了頁面生成之外的其他地方還使用了Velocity（比如發送郵件）。A minor point is that 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. Typically this occurs when Velocity is used within a web application outside of web page generation (e.g. for sending email).
指南Tutorial
下面是一個介紹使用VelocityViewServlet來建立一個簡單的web應用的簡要教程。更多的信息請參見Velocity Tools 的文檔。What follows is a brief tutorial on building a simple web app with VelocityViewServlet. For more information, consult the Velocity Tools documentation.
- 從 download page 下載Velocity Tools項目的源代碼。里面包含了下面介紹的這個例子的代碼。Download the Velocity Tools project source (you need the source for the examples) from download page .
- 請確保你的 Apache Ant 環境安裝正確。If you haven't already installed Apache Ant . do so now.
- 使用下面的指令來構建VelocityTools的jar包和"simple"示例。Build the Velocity Tools jar and the "simple" example by typing: ant example.simple
- 察看"examples"文件夾，在里面你會發現一個叫"index.vm"的文件，下面是這個文件的摘錄：Take a look at the "examples" directory. You will see a file "index.vm". Here's an excerpt: <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文件夾下，你會發現一個"toolbox.xml"文件，在這個文件里面就定義了自動放在Velocity上下文中的對象的列表。You can copy any additional velocity files into this same directory. In examples/WEB-INF you will see a file "toolbox.xml". This specifies a list of "Tools" that are automatically included in the context. <toolbox> <xhtml>true</xhtml>
<tool>
<key>toytool</key>
<class>ToyTool</class>
</tool>
<data type="number">
<key>version</key> <value>1.1</value>
</data>
<data type="boolean">
<key>isSimple</key> <value>true</value>
</data>
<data type="string">
<key>foo</key> <value>this is foo.</value>
</data>
<data type="string">
<key>bar</key> <value>this is bar.</value>
</data>
<tool>
<key>map</key>
<class>java.util.HashMap</class>
</tool>
<tool>
<key>date</key>
<scope>application</scope> <class>org.apache.velocity.tools.generic.DateTool</class> </tool>
</toolbox>
最后，應用的web.xml文件里面定義了接受請求的servlet和toolbox的配置文件位置。And finally the web.xml file specifies the name of the servlet and location of toolbox.properties. <web-app> <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>
<load-on-startup>10</load-on-startup>
</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）會讓你更容易通過改變或者添加一些東西來做些實驗。現在，你可以通過下面的地址來訪問頁面了。（地址隨著你的項目的名字改變）Copy this directory into your "webapps" directory on Tomcat. You could also copy "simple.war", but copying in the entire directory will let you experiment with changes. You should now be able to access your simple one-page webapp with this URL. (or something similar): http://localhost:8080/simple/index.vm
- 嘗試添加一些新的Velocity頁面。注意，你只需要改變訪問的URL地址就可以訪問新的頁面了。嘗試改變toolbox.xml中的一些內容，或者向其中添加你自己的Tools。察看examples/WEB-INF的文檔，或者Wiki 來得到更多的工具的使用信息。Experiment with adding new Velocity pages. Note that you can access any velocity page just by changing the URL. Try changing the entries in toolbox.xml or creating your own tools. Consult the Velocity Tools documentation and the Wiki for more info on the wide variety of tools available.