《Velocity java開發指南》中文版(上)轉載

文章引自：http://sakyone.iteye.com/blog/524289

1.開始入門
Velocity是一基於java語言的模板引擎，使用這個簡單、功能強大的開發工具，能夠很容易的將數據對象靈活的與格式化文檔組裝到一塊兒；但願本文能指引使用velocity在開發基於servlet或通常java應用程序的應用上快速起步。
1.Getting Started
取得Velocity並在你的機器上開始運行很容易,如下是所有詳細的說明:
取得Velocity發佈版本，go here。
目錄及文件說明:
Velocity-X.jar 完整的velocity jar包通常命名格式爲velocity-X.jar，其中X是當前版本號。注意這個jar包不包含Velocity所必須依賴的其它jar包(具體見後)。
SRC:完整的源文件代碼目錄
Examples. 完整的aplication或web App例子。
docs :Veocity文檔目錄
build: 使用ant編譯源碼時所需的lib.
OK，如今就能夠開始使用了.請將Velocity-x.jar放到你的classpath中或webapp的lib下。
固然，咱們強烈建議你先運行其中的例子，以感覺Velocity的優異之處.
2.Dependencies 依賴資源
Velocity可運行於JDK1.4或JRE1.4及其以上版本.
Velocity也依賴於其它一些jar包，在分發版本的 build/lib 有,若是你下載的是二進制分發版本，須要到如下地址下載其它依賴包.
Jakarta Commons Collections – 必須.
Jakarta Avalon Logkit – 可選，但強列建議加上，以便輸出日誌信息.
Jakarta ORO – 可選，僅當用到org.apache.velocity.convert.WebMacro template 這個模板轉換工具時.
2.參考資源：
一些優秀的資源和例程列表以下：
開發者郵件列表 mail-lists.
郵件檔案表 : http://www.mail-archive.com是很好的一個資源庫.能夠以’Velocity’爲關鍵字進行搜索。
源代碼(源碼分發版本) : src/java/... : 含有Velocity project的全部源碼
應用程序例程1 : examples/app_example1 : 一個很簡單的示例如何在通常應用程序中使用Velocity.
應用程序例程1 2 : examples/app_example2 : 如何在應用程序中使用Velocity工具類.
servlet example : examples/servlet_example1 :示例如何在servlet中用Velocity 輸出模板.
logger example : examples/logger_example : 如何定製Velocity的日誌工具.
XML example : examples/xmlapp_example : 使用 JDOM 從 Velocity 模板讀取內容. 還包含一個遞歸調用宏的示例.
event example : examples/event_example : 在Velocity 1.1 中使用事件處理API。
Anakia application : examples/anakia : 示例用stylesheet 美化 xml 數據。
Forumdemo web app : examples/forumdemo : 一個基於servlet的論壇功能實現示例.
templates : test/templates :全面展現VTL(Velocity Template Lanauage)功能的模板集合。
context example : examples/context_example : 兩個示例如何重寫(繼承) Velocity context 功能的例子(針對高級用戶).

3.它是如何工做的？
1.基本使用模式
在application program或servlet中使用Velocity中，通常經過以下步驟：
對於全部應用，第一步是要初始化Velocity, 通常使用惟一實例模式(Singleton)，如Velocity.init().
建立一個Context object.
將你的數據對象加入到Context對象中.
使用Velocity選擇一個模板.
合併模板和數據導出到輸出流.
下面的代碼，經過使用org.apache.velocity.app.Velocity的單實例模式，合併輸出：

import java.io.StringWriter;
import org.apache.velocity.VelocityContext;
import org.apache.velocity.Template;
import org.apache.velocity.app.Velocity;
import org.apache.velocity.exception.ResourceNotFoundException;
import org.apache.velocity.exception.ParseErrorException;
import org.apache.velocity.exception.MethodInvocationException;

//初始化
Velocity.init();
//取得VelocityContext對象
VelocityContext context = new VelocityContext();
//向context中放入要在模板中用到的數據對象
context.put( "name", new String("Velocity") );
Template template = null;
//選擇要用到的模板
try
{
   template = Velocity.getTemplate("mytemplate.vm");
}
catch( ResourceNotFoundException rnfe )
{
   // couldn't find the template
}
catch( ParseErrorException pee )
{
// syntax error : problem parsing the template
}
catch( MethodInvocationException mie )
{
// something invoked in the template
// threw an exception
}
catch( Exception e )
{}

StringWriter sw = new StringWriter();
//合併輸出
template.merge( context, sw );

以上是基本的使用模式，看起來很是簡潔！這些都是通常狀況下使用Velocity所必須的步驟. 但你可能不想這樣循序漸進的編寫代碼 –Velocity提供了一些工具以更容易的方式在servlet或應用程序中使用。在這個指南的後面, 咱們將討論在servlet和普通應用程序中更好的用法.

4.單實例仍是多實例(To Singleton Or Not To Singleton...)?
1.Singleton Model
這是系統默認的模式, 這樣在jvm(應用程序)或web aplication(一個web程序)中只存在一個Velocity engine實例共享使用。. 這對於配置和共享資源來講很是方便. 好比, 這很是適合用於支持 Servlet 2.2+ 的web application中，每個web app持有它本身的惟一Velocity實例, 它們能夠共享templates, a logger等資源. Singleton能夠直接經過使用org.apache.velocity.app.Velocity 類, 以下例子:

import org.apache.velocity.app.Velocity;
import org.apache.velocity.Template;

/*
* Configure the engine - as an example, we are using
* ourselves as the logger - see logging examples
*/

Velocity.setProperty( Velocity.RUNTIME_LOG_LOGSYSTEM, this);

/*
* now initialize the engine
*/

Velocity.init();


Template t = Velocity.getTemplate("foo.vm");

2.Separate Instance
在1.2版本之後, 能夠在 JVM (or web application.)建立，配置，使用多個Velocity實例；當你但願在同一程序中，對每一個實例獨立配置時它們的 template directories, loggers等資源時，這是很是方便的. 多實例化時，咱們要用到 org.apache.velocity.app.VelocityEngine類. 下面是一個例子，請注意和上面singleton example同法時的不一樣:

import org.apache.velocity.app.VelocityEngine;
import org.apache.velocity.Template;

...

/*
* create a new instance of the engine
*/

VelocityEngine ve = new VelocityEngine();

/*
* configure the engine. In this case, we are using
* ourselves as a logger (see logging examples..)
*/

ve.setProperty( VelocityEngine.RUNTIME_LOG_LOGSYSTEM, this);

/*
* initialize the engine
*/

ve.init();

...

Template t = ve.getTemplate("foo.vm");

能夠看到，這是很是簡單的直接使用就好了.不管用singleton 或 separate instances都不須要改變你程序的上層結構及模板內容.
對於開發人員而言, 你應在如下兩個類中兩者擇一的使用
org.apache.velocity.app.Velocity 應用於 singleton model, org.apache.velocity.app.VelocityEngine通常用於non-singleton model ('separate instance').


5. The Context
1.The Basics
'context' 是Velocity中的一個核心概念, 這是一個從系統的」數據容器(a container of data)」引出的一個常見概念. 這裏的context在java程序層和模板視圖層(template layer ( or the designer ))之間扮演着一個」數據對象傳送者」'(carrier')的角色.
作爲程序員，你能夠將你程序生成的不一樣類型的數據對象放入context中，對於視圖設計來講，這些對象(包含它們的數據域和命令)將在模板元素 中被引用到(references)。通常來講，你將和視圖設計者一塊兒決定應用須要哪些數據，能夠說，你放入context中的數據對象在這裏成爲一 種」API」,由視圖設計者在模板中來訪問.所以，在向context中決定放放哪些數據對象時，程序的設計者須要仔細分析視圖表現所需的數據內容。
雖然Velocity中你能夠建立本身的Context類來支持一些個性化的應用(好比，一個訪問，保存LDAP Server服務的context),你能夠實現VelocityContext這個己封裝較爲完務的基類。
VelocityContext對象基本上可知足大多的應用, 咱們強烈建議你除非在特別的狀況下，不然不要建立本身的Context實現！
VelocityContext用法十分簡單，相似於Hashtable class.下面是這個接口提供的兩個基本用法：
public Object put(String key, Object value);
public Object get(String key);
很像Hashtable吧,這裏的value必須是一個java.lang.Object類(不能是原始類型，像int,boolean), 也不能是null值. 原始類型(Fundamental types like int or float)必須被包裝爲一個適當對應的Object型.
OK,以上就是context 對象的用法概念，很簡單咱們卻哆嗦這麼：）. 關於其更多的介紹，請見API documentation.
2.在模板中用#foreach指令支持迭代對象
在放入context前，你對對象有着全面的操做自由. 但就像全部的自由同樣, 你必須遵照一些規則，承擔一些責任，所以，你必須理解Velocity是如何使用對象的，Velocity的VTL支持多種類型的集合類型 (collection types) 使用#foreach().
Object [] 通常對象數組. Velocity將內功能會將它包裝成功之爲一個實現Iterator interface對象, 這個轉換是不須要程序員或視圖設計者參與.
java.util.Collection :Velocity會使用他們的標準iterator() 獲得一個能夠迭代中使用的 Iterator對象,若是你使用本身的實現了Collection interface的對象，要確保它的iterator() 命令返回一個可用的Iterator.
java.util.Map接口對象,Velocity 使用其頂層接口的values() 命令獲得一個實現 Collection interface的對象, 應用其iterator()再返回一個Iterator.
java.util.Iterator使用特別注意 : 若是一個Iterator對象被放置到context中，當在模板中有多個 #foreach()指令中,這些#foreach() 將順序執行，若是第一個調用失敗，後面的將阻塞且不能重置.
java.util.Enumeration USE WITH CAUTION : 如同java.util.Iterator同樣的道理,Velocity將使用的是一個不能重置（'non-resettablity'）或者說一個final型的對象.
所以，僅當在不得己的狀況下，Iterator and Enumeration 對象纔有必要放入context中---也許你有更好的辦法不使用他們.
例如，你能夠將以下代碼:
Vector v = new Vector();
v.addElement("Hello");
v.addElement("There");

context.put("words", v.iterator() );

替換爲:
context.put("words", v );

3.Context Chaining
另一個新引入的概念是context chaining.有時也叫作context wrapping(有點相似與servlet中的chain), 這個高級特性讓你能夠連結多個獨立的Velocity的contexts,以便在template中使用.
如下是這種用法的代碼示例 :

VelocityContext context1 = new VelocityContext();

context1.put("name","Velocity");
context1.put("project", "Jakarta");
context1.put("duplicate", "I am in context1");

VelocityContext context2 = new VelocityContext( context1 );

context2.put("lang", "Java" );
context2.put("duplicate", "I am in context2");

template.merge( context2, writer );

在 上面的代碼中, context2 作爲context1的chains. 這意味着你在模板中可使用放入這兩個context中的任何一個對象, 當兩個context中有相同的key中，在模板中輸出時，將會輸出最後一個key的值，如上例key爲duplicate的值將輸出爲 "I am in context2".
其實，在上例中不存在duplication, 或'covering', context1中的string "I am in context1" 依然能夠經過context1.get("duplicate")方法獲得. 但在上例中，模板中引用 '$duplicate' 將會返回 'I am in context2', 並且模板不能再訪問到context1中的'I am in context1'.
另外要注意的是，當你嘗試在模板中加入信息，好比使用#set()聲明,這將對所己輸出的模板產生影響.
如前所述， Velocity context類也是或擴展的, 但在這份指南中沒有述及. 若是你有興趣,能夠查看org.apache.velocity.context 中的代碼以瞭解contexts 是如何生成，java數據對象以何機制傳出的. 例程 examples/context_example有一些示例展示.
4.模板中的己建立對象
Java代碼中的數據對象與模板交互有兩種常見方式：
模板設計者從模板中執行程序員放入到context中的java對象的命令:
#set($myarr = ["a","b","c"] )
$foo.bar( $myarr )
當模板加入一個對象到context中，模板合併輸出後，java代碼將能夠訪問這些對象.
#set($myarr = ["a","b","c"] )
#set( $foo = 1 )
#set( $bar = "bar")
這裏述及這些技巧有些過早,但如今必須理解如下概念:
The VTL經過context或method所傳的 [ 1..10 ] and ObjectArray ["a","b"] 是java.util.ArrayList對象. 所以你的對象的命令設計時，要具備兼容性.
Numbers在context中將被包裝爲Integers, strings，固然就是Strings了.
Velocity會適當的根據調用的參數類型適配對象的調用命令, setFoo( int i )將一個 int 放入context 和 #set()是不會衝突的.
5.Context對象的其它用法
每個VelocityContext（或任意源自AbstractContext）的對象，都是一個封裝好指定規則的的存儲節點，對於通常開發都來講,只需使用就是.但這裏還有一些你應知道的特性：
考慮如下狀況:
你的模板重複使用VelocityContext object.
Template caching is off.
反覆調用getTemplate() 命令.
這都有可能引發 VelocityContext的內存泄露( 'leak' memory )---當它聚集過多的數據對象時,所以強烈建議你作到如下幾點 :
在每一個模板渲染過種中(template render process)建立一個新的VelocityContext. 這會防止過多的cache data. 當須要重用一個 VelocityContext 由於它內部己放置了數據對象, 你只須要像這樣簡單的包裝一下:VelocityContext useThis = new VelocityContext( populatedVC );具體能夠參看 Context chaining 獲取更多信息.
打開模板的caching功能. 以防止重複解析模板,固然，這會要求服務器有更高的性能.
在迭代操做時，要重用模板對象. 這樣將不會對Velocity形成過大壓力, 若是緩存關閉, 就須要每次都讀取和解析模板, 致使 VelocityContext 中每次都要保存大量新的信息.

6.Using Velocity In Servlets
1.Servlet Programming
Velocity最一般用在servlet中作爲www服務. 有很是多的理由告訴你這項任務是最適合Velocity完成的,最重要的一個就是Velocity's能夠分離視圖(表現層和)代碼層.在這裏能夠看到更多的理由this.
在servlet中使用Velocity是很是簡單的. 你只須要extend 己有的 VelocityServlet class和一個必須實現的方法： handleRequest().
public Template handleRequest( HttpServletRequest, HttpServletResponse, Context )
這個方法直接傳送HttpServletRequest 和 HttpServletResponse objects,. 這個方法能夠返回null值表示全部處理己經完成, 相對而言，指示velocity調用velocity requestCleanup()更爲經常使用. 以下代碼示例(在例程中有)

public class SampleServlet extends VelocityServlet
{
    public Template handleRequest( HttpServletRequest request,
                                   HttpServletResponse response,
                                   Context context )
    {

        String p1 = "Jakarta";
        String p2 = "Velocity";

        Vector vec = new Vector();
        vec.addElement( p1 );
        vec.addElement( p2 );

        context.put("list", vec );

        Template template = null;

        try
        {
            template = getTemplate("sample.vm");
        }
        catch( ResourceNotFoundException rnfe )
        {
         // couldn't find the template
        }
        catch( ParseErrorException pee )
        {
          // syntax error : problem parsing the template
        }
        catch( Exception e )
        {}

        return template;
    }
}

看起來好熟悉吧? 除過處理一些異常，基本的功能Velocity都己爲你準備好了, 就連在應用程序中要你寫的merge() 這一步，VelocityServlet本身也己處理,這就是基本的用法：取得context, 加入咱們本身的對象最後返回模板 template.
默認的 Context是做爲 handleRequest() 傳入的. 可使用如下常量直接訪問 request和response對象，VelocityServlet.REQUEST (value = 'req') and VelocityServlet.RESPONSE (value = 'res') ,以下是java例程 :

public Template handleRequest( Context context )
{
    HttpServletRequest request = (HttpServletRequest) context.get( REQUEST );
    HttpServletResponse response = (HttpServletResponse) context.get( RESPONSE );

   ...
}

能夠在模板中以下訪問:
#set($name = $req.getParameter('name') )

一些更高級的用法，如VelocityServlet base class 能夠在處理請求時重寫更多的簽名方法 :

Properties loadConfiguration( ServletConfig )
這能夠重寫常規的配置方法. 這經常使用在修改日誌路徑或運行時改寫webapp root的絕對路徑.

Context createContext(HttpServletRequest, HttpServletResponse )
你能夠建立本身的Context object. 這可使用更高級的技術, 如數據鏈或預載數據和工具類. 默認的實理僅返回一個己內置request and response 對象的VelocityContext.你直以在模板中直接訪問他們的命令。

void setContentType( HttpServletRequest,HttpServletResponse )
你能夠本身定義contentType, 或提取client定義的. 默認的contentType類型在velocity.properties文件中配置, 通常來講，默認的"text/html" 類型是不夠詳細的.

void mergeTemplate( Template, Context, HttpServletResponse )
你能夠生成輸出流(output stream). VelocityServlet使用含有多種輸出對象的池, 在特定情形下，重寫這個命令是有用的.

void requestCleanup( HttpServletRequest, HttpServletResponse , Context )
這個調用通常在處理完後作資源的清理工做，若有須要，在這個命令的重寫內容中加上你的代碼.

protected void error( HttpServletRequest, HttpServletResponse, Exception )
在處理中，當錯誤發生時，這個方法會被調用. 默認的實現是將發送一個簡單的HTML格式的錯誤內容到客戶端. 你能夠重寫以定製錯誤處理.
更多的信息，請參考 API documentation.


2.Deployment
發佈基於Velocity的servlets 時，須要參數來配置 Velocity runtime. 在Tomcat上, 一個簡單的方法是將velocity.properties文件放到你的webApp root目錄下 (webapps/appname ) 而後在 WEB-INF/web.xml 文件中加上如下幾行 :

引用

<servlet>
<servlet-name>MyServlet</servlet-name>
<servlet-class>com.foo.bar.MyServlet</servlet-class>
<init-param>
      <param-name>properties</param-name>
      <param-value>/velocity.properties</param-value>
</init-param>
</servlet>

以上配置將確保MyServlet 能夠被載入，Velocity也將會使velocity.properties來初始化.
注意： Velocity 在運行時使用的是單實例模式, 所以將 velocity-XX.jar放到YourWebAPP/WEB-INF/lib目錄便可. 但當多個webApp要使用時，放入CLASSPATH 或Servlet容器的頂層 lib是最好的選擇.
7. Using Velocity In General Applications
Velocity被設計爲一個通用的功具包,它也經常使用於通常的應用程序中. 如這篇指南開始所討論的那樣, 另外，這裏還有一些對通常應用程序來講頗有用的工具類:
1.The Velocity Helper Class
Velocity 提供一個 utility class ( org.apache.velocity.app.Velocity ). 這個類中提共一個初始化Velocity所必需的方法, 具體的細節能夠到文檔中查看.
Velocity runtime engine在運行時是單實便模式，它能夠給 Velocity的用戶經過同一個jvm提供日誌，資源訪問方法. 這個engine運行時僅初始化一次. 固然，你能夠嘗初對init()進行屢次調用, 但只有第一次有效. The Velocity utility class 目前提供5個命令來配置運行時engine:
這5個配置方法是 :
setProperty( String key, Object o )
這麼簡單，不用解釋了吧.
Object getProperty( String key )
嗯，也不說了
init()
用默認的參數文件初始化
init( Properties p )
用一個特定的java.util.Properties對象初始化.
init( String filename )
用指定名字的參數文件初始化
注意：除非你指定了，不然初始時會使用默認參數. 僅當在調用init()時的配置會對系統生效。
通用的 initializing Velocity 通常步驟以下:
設置你指定的配置參數值在文件org/apache/velocity/runtime/defaults /velocity.properties中，或放入java.util.Properties, 在第一次調用init( filename )或 init( Properties ) .
單獨設置每一個配置參數經過調用 setProperty(),最後調用init(). 這適合一些一有本身的CMS系統(configuration management system )程序。
運行時一但初始化, 你就能夠開始工做了.. 只須要考慮組裝什麼樣的數據對象到你的輸出模板上, Velocity utility class 能夠幫你更容易作到這些.這裏有一些命令摘要描述以下 :

evaluate( Context context, Writer out, String logTag, String instring )
evaluate( Context context, Writer writer, String logTag, InputStream instream )

這個命令用來修飾輸入流,你能夠將包含TVL的模板文件從內置的String對象、DB、或非文件系統的數據源輸入，.
invokeVelocimacro( String vmName, String namespace, String params[], Context context, Writer writer )
你能夠直接訪問Velocimacros. 也能夠經過evaluate()命令來完成,這裏你只需簡單的傳入VM文件名(模板文件), 建立一組VM參數放到Context,而後輸出. 注意放入Context的參數必須是鍵-值對出現的.
mergeTemplate( String templateName, Context context, Writer writer )
這個命令用來執行Velocity的模板合併和渲染功能. 它將應用context中的數據對象到指定文件名的模板中.將結果輸出的指定的Writer. 固然，若是沒有特別的須要，不建議這麼作.
boolean templateExists( String name )
檢測當前配置的資源中，是否存在name的模板名.
這樣，咱們就更容易編寫使用Velocity的java代碼了. Here it is

import java.io.StringWriter;
import org.apache.velocity.app.Velocity;
import org.apache.velocity.VelocityContext;

public class Example2
{
    public static void main( String args[] )
    {
        /* first, we init the runtime engine. Defaults are fine. */

        Velocity.init();

        /* lets make a Context and put data into it */

        VelocityContext context = new VelocityContext();

        context.put("name", "Velocity");
        context.put("project", "Jakarta");

        /* lets render a template */

        StringWriter w = new StringWriter();

        Velocity.mergeTemplate("testtemplate.vm", context, w );
        System.out.println(" template : " + w );

        /* lets make our own string to render */

        String s = "We are using $project $name to render this.";
        w = new StringWriter();
        Velocity.evaluate( context, w, "mystring", s );
        System.out.println(" string : " + w );
    }
}

運行如上程序，在運行程序的目錄下將獲得模板文件testtemplate.vm (默認配置中模板文件的輸出位置是當前目錄):

引用

template : Hi! This Velocity from the Jakarta project.

string : We are using Jakarta Velocity to render this.

where the template we used, testtemplate.vm, is
Hi! This $name from the $project project.

在這裏，咱們不得不使用 mergeTemplate() and evaluate() in our program. 這主要是爲了示例. 在通常應用中，這是不多使用到的，但咱們提供了根據具體須要自由使用的途徑.
這有點不和咱們這篇文張本意的「基礎功能指南」這一意圖, 但我想這是必須知道的. 首先, 你獲得一個放置了數據對象的context對象, 不用的是使用了命令 mergeTemplate(), mergeTemplate() 所作的工做是合併模板, 在運行時調用低層功能(lower-level). 接下來，經過evaluate()方法使用一個String動態生成模板.
這是一樣簡單的使用Velocity engine的方式，這些可選功能也許能夠幫你作一些重複的工做，好比生成模板的模板：）

2.Exceptions
There are three exceptions that Velocity will throw during the parse / merge cycle在解析/合併(parse/merge)模板週期中，Velocity或能出現三個Velocity異常.另外，還可能會有 IO problems, etc. Velocity自定義的異常能夠在package org.apache.velocity.exception:
ResourceNotFoundException
當velocity的資源管理器沒法找到系統請求的資源時出現.
ParseErrorException
當parse模板文件中的 VTL 語法出錯時出現.
MethodInvocationException
Thrown when a method of object in the context thrown an exception during render time,當處理模板中，context中的對象的命令調用出錯時.
固然，每一次出錯時，相關的消息內容會保存到運行時的日誌文件中，獲取更多資料，請查看API文檔。

3.其它細節
在以上的一些例程中，使用默認的properties配置你的程序很是方便. 但你能夠根據本身的須要，用本身的配置文件經過在Velocity中調用init(String yourFileName)命令傳入你的配置文件名, 或建立一個保存了你的配置參數的 java.util.Properties對象，經過調用 init(Properties)命令來實現. 這其中後一個方式是很便捷的, 你能夠直接將一個獨立的參數文件經過load()調用，將其中的配置參數置入Properties對象中. 你還能夠作得列好---你能夠在運行時運態的從你的程序框架中加入參數. 這樣，你應能夠將Velocity的配置參數和你原來應用的配置在不作大的更改狀況下共用。
當須要從一個指定的目錄提取模板文件時(默認爲當前目錄),你能夠這樣作 :

import java.util.Properties;
...

public static void main( String args[] )
{
    /* first, we init the runtime engine. */

    Properties p = new Properties();
    p.setProperty("file.resource.loader.path", "/opt/templates");
    Velocity.init( p );

    /* lets make a Context and put data into it */

...

這樣，Velocity在須要時，將自動到/opt/templates目錄下查找模板文件,若是有問題能夠查看velocity.log中所記錄的出詳細出錯信息。它會幫你有效的消息錯誤.