Velocity开发手册学习笔记

原文地址
http://velocity.apache.org/engine/releases/velocity-1.6.4/developer-guide.html

How Velocity Works

1.Initialize Velocity. This applies to both usage patterns for Velocity, the Singleton as well as the 'separate runtime instance', and you only do this once.
2.Create a Context object.
3.Add your data objects to the Context.
4.Choose a template.
5.'Merge' the template and your data to produce the ouput.

To Singleton Or Not To Singleton
Singleton Model org.apache.velocity.app.Velocity
Separate Instance org.apache.velocity.app.VelocityEngine
不要改动org.apache.velocity.runtime
可以改动org.apache.velocity.app

The Context
数据容器。从java到模板的数据传输。
也算是一个API。
public Object put(String key, Object value);
public Object get(String key);
注意，like a Hashtable, the value must be derived from java.lang.Object, and must not be null.

Support for Iterative Objects for #foreach()
Object []，velocity自动把它包装成一个Iterator,并且，在1.6之后，可以直接在它之上调用List的方法。
java.util.Collection
java.util.Map
java.util.Iterator USE WITH CAUTION: This is currently supported only provisionally - the issue of concern is the 'non-resettablity' of the Iterator. If a 'naked' Iterator is placed into the context, and used in more than one #foreach(), subsequent #foreach() blocks after the first will fail, as the Iterator doesn't reset.
java.util.Enumeration USE WITH CAUTION: Like java.util.Iterator
Any public class with a public Iterator iterator() method that never returns null.

尽量不要把Iterator直接放入context,不可避免时要小心（大数据）。

Support for "Static Classes"

Context Chaining
Note:The changes to the context via #set() statements in a template will affect only the outermost context. 如果要在rendering后使用，注意不要扔掉outer context.

Objects Created in the Template
•The VTL RangeOperator [ 1..10 ] and ObjectArray ["a","b"] are java.util.ArrayList objects when placed in the context or passed to methods. Therefore, your methods that are designed to accept arrays created in the template should be written with this in mind.
•VTL Map references are unsurprisingly stored as java.util.Map.
•Decimal numbers will be Doubles or BigDecimals in the context, integer numbers will be Integer, Long, or BigIntegers, and strings will be, of course, Strings.
•Velocity will properly 'narrow' args to method calls, so calling setFoo( int i ) with an int placed into the context via #set() will work fine.

重要的问题
满足以下条件的情况下有可能内存泄露。
•You are iterating over the same template using the same VelocityContext object.
•Template caching is off.
•You request the Template from getTemplate() on each iteration.

其原因是VelocityContext (or any Context derived from AbstractContext) is node specific introspection caching.

解决办法
•Create a new VelocityContext for each excursion down through the template render process.
•Turn on template caching.
•Reuse the Template object for the duration of the loop iterations.


Using Velocity
可以调用Velocity的方法来实现Velocity的工作。
异常也设计的一看异常信息就知道错误在什么地方。


Application Attributes

Configuring Event Handlers

IncludeEventHandler
InvalidReferenceEventHandler
MethodExceptionEventHandler
NullSetEventHandler
ReferenceInsertionEventHandler

注册Handler，全局Handler，和一个Context建立关联。


Velocity Configuration Keys and Values
Configuring Logging
Configuring Resource Loaders
Template Encoding for Internationalization


Velocity and XML
转换xml文档。

被骗了，以为你有自己整理过的文档呢！

这个模块技术，让我纠结的是，有时间变量变成数据的时候，会有许多空格，不知道怎么办

不好意思，也许题目起的不好，这是一个精简版的备忘录。