Velocity配置文件详解

Velocity的运行时有各种可配置的属性，让我们来仔细了解一下这些属性。我们把这些属性分成5个类型来进行讨论：指令、编码（encoding）、日志（logging）、资源管理和其他。
1.指令
下面的指令将影响某几个Velocity指令的行为。
directive.foreach.counter.name
directive.foreach.counter.name属性用于指定VTL标识符，用于#foreach指令的循环计数器名称。当使用了前缀$时，这个标识符用作Velocity变量引用，它允许模板设计者访问#foreach指令的当前反复数（即循环数）。默认情况下，这个计数器从1开始，且每一次循环的增量为1。directive. foreach.counter.name属性的值默认为velocityCount，其相应的变量引用为$velocityCount。如果模板设计者想用引用名称$my-Count来代替这个值，则可以为该属性赋值为myCount。

directive.foreach.counter.initial.value
directive.foreach.counter.initial.value属性指定了#foreach指令的循环计数器初始值，这个值通过循环计数器引用提供（见directive.foreach.counter.name属性），作为每一个后来反复的起点，这个值将增加一个步长（At the beginning of each subsequent iteration, the value is incremented by one）。directive.foreach.counter.initial.value的默认值是1。熟悉的C++和Java loop循环的模板设计者或许更喜欢基于0的计数器，那么你把这个属性设置为0即可。

directive.include.output.errormsg.start
directive.include.output.errormsg.start属性指定了在（由非法输入参数被传递到#include指令而产生的）错误信息之前的文本。比如错误输入了一个未定义或不明确的（undefined）Velocity引用，将触发这种错误信息。这个错误信息前缀通过定义这个属性来指定。其默认值为“<!-- include error :”。

directive.include.output.errormsg.end
directive.include.output.errormsg.end属性指定了跟随在（由非法输入参数被传递到#include指令而产生的）错误信息之后的文本。比如错误输入了一个未定义或不明确的（undefined）Velocity引用，将触发这种错误信息。这个错误信息后缀通过定义这个属性来指定。其默认值为“see error log -->”。

directive.parse.max.depth
directive.parse.max.depth属性指定了#parse指令可以嵌套的最大深度。当值为1时，从本质上已经禁用了#parse指令，当一个模板包含了#parse指令时，深度的值就已经为1了，所以该值至少为1。虽然该属性的主要目的是为了防止递归失控，但该深度限度也适用于普通不含递归的#parse嵌套。其默认值为10。

2.编码（Encoding）
下面的属性用于指定模板和数据的编码（The following properties specify encodings to be associated with templates and data used by certain tools associated with the Velocity template engine）。
input.encoding
input.encoding属性被用于指定模板引擎进行模板处理的编码。一旦设定好后，所有的模板输入都将转换为指定的编码。默认值为ISO-8859-1。所支持的编码依赖于Java字符集。

output.encoding
output.encoding属性被用于指定输出流的编码。这个不是多种用途的Velocity属性，通常情况下，仅供VelocityServlet类和Anakia项目使用。普通情况下，在Writer被合并之前，编码可以在Writer类实例的初始化时直接指定。其默认值为ISO-8859-1。

3.日志（Logging）
下面的属性将影响Velocity日志系统的行为。
runtime.log
runtime.log属性用于指定Velocity日志文件的路径。默认情况下，这个路径被指定为应用程序的相对路径，这个设置可以通过file.resource.loader.path属性（下面将要讨论的）定义来修改。runtime.log属性的默认值是velocity.log。通过前面的示例，对这个文件你应该比较熟悉了，每一次运行Velocity应用程序里，就会产生这个文件。

runtime.log.logsystem
runtime.log.logsystem属性定义了一个Velocity将要传递（hand off/手传手？）日志任务的对象，用于Velocity。为了使用这个对象，你需要有一个实现org.apache.velocity.runtime. log.LogSystem接口的类。这个属性主要用于当Velocity的日志需要与定制应用程序日志类结合的情况下。该属性没有默认值，同时要注意，该属性值最好是一个对象（当然也可以用字符串），它不可以被直接指定为配置文件或Java属性对象。

runtime.log.logsystem.class
runtime.log.logsystem.class属性用于指定运行时实例化Velocity日志服务的类。该属性的值可以由逗号分隔的类名称列表组成。运行时引擎按列表里的名称次序依次查找匹配的类。第一个匹配的类将用于Velocity日志的实例化。默认值为“org.apache.velocity. runtime.log.AvalonLogSystem, org.apache.velocity.runtime.log.SimpleLog4J logSystem”。日志功能也可以通过把该属性设置为org.apache.velocity. runtime.log.NullLogSystem而禁用。

runtime.log.error.stacktrace
runtime.log.error.stacktrace属性用于指定当Velocity运行时引擎记录错误日志时，是否允许产生和日志堆栈跟踪信息（既是否产生堆栈的跟踪日志信息）。虽然它自己支持这个功能，但其关联的功能仍旧没有实现（Although support for the property itself exists, the associated functionality is not yet implemented）。默认值为false。

runtime.log.warn.stacktrace
runtime.log.warn.stacktrace属性用于指定当Velocity运行时引擎日志一个警告时，是否允许产生和日志堆栈跟踪信息。虽然它自己支持这个功能，但其关联的功能仍旧没有实现（Although support for the property itself exists, the associated functionality is not yet implemented）。默认值为false。

runtime.log.info.stacktrace
runtime.log.info.stacktrace属性用于指定当Velocity运行时引擎日志一个报告信息时，是否允许产生和日志堆栈跟踪信息。虽然它自己支持这个功能，但其关联的功能仍旧没有实现（Although support for the property itself exists, the associated functionality is not yet implemented）。默认值为false。

runtime.log.invalid.references
runtime.log.invalid.references属性用于指定是否要对模板里的非法Velocity引用错误进行日志。如果值为true，非法引用将产生一个警告信息。如果值为false，将忽略非法引用的信息。默认值为true。

4.资源管理
下面的属性将影响Velocity资源管理系统的行为。
resource.manager.class
resource.manager.class属性用于指定处理Velocity资源管理任务的类实例。这个类必须是已经实现了org.apache.velocity.runtime.resource.ResourceManager接口的类。默认值是org.apache.velocity.runtime.resource.ResourceManagerImpl。

resource.manager.cache.class
resource.manager.cache.class属性用于指定（代表资源管理）处理资源缓存请求的类实例，这个类必须是已经实现了org.apache.velocity.runtime.resource.ResourceCache接口的类。默认值是org.apache.velocity.runtime.resource. ResourceCacheImpl。

resource.manager.logwhenfound
resource.manager.logwhenfound属性用于指定当资源管理定位一个得到的资源时是否对相关信息进行日志。默认值是true，即允许对这样的信息进行日志。

resource.loader
resource.loader属性用于指定资源加载器的详细名称，为了通过Velocity属性定义资源加载器的行为，这个名称只用作标签（The resource.loader property associates a name with a particular resource loader. This name is used only as a label to further define the resource loader’s behavior via Velocity properties）。
紧随其后的部分，我们用字符串<loader>提交这些名称。在velocity.properties文件只定义了一个名叫file的资源加载器，在这里，我们把其相应的属性名称用<loader>来列出（替换了file）（In the following subsections, we use the string <loader> when referring to this name. The velocity.properties file defines only one resource loader, which it names file, and the corresponding property names are those listed in the following subsections with <loader> replaced by file）。我们将在稍后详细讨论资源加载的更多细节。

<loader>.resource.loader.description
resource.loader.description属性指定了一个文本的资源加载器描述符。这个属性只是定义一个报告信息，实现上它不会影响资源加载器的功能。velocity.properties文件为该属性提供了一个Velocity File Resource Loader的值。
<loader>.resource.loader.class
resource.loader.class属性用于指定加载关联资源类型的类。该类继承自Velocity的org.apache.velocity. runtime.resource.loader.ResourceLoader类，用于提供特定的资源类型。velocity.properties文件为file.resource.loader.class属性提供了一个org.apache.velocity.runtime.resource.loader.FileResourceLoader的值。

<loader>.resource.loader.path
resource.loader.path属性用于指定一个关联类型资源的根目录。为资源提供的任何位置都是相对于这个根目录的。velocity.properties文件为file.resource.loader.path属性提供了一个值：“.”，它确定了应用程序的根目录（这个根目录又相对于模板、日志文件资源等）。

<loader>.resource.loader.cache
resource.loader.cache属性用于指定是否允许在加载时缓存某几个资源。velocity.properties文件为file.resource.loader.cache属性提供了一个值：false。意思是防止从缓存模板加载文件资源，在开发和调试阶段是首选值。在生产阶段，值true是最好的选择。

<loader>.resource.loader.modificationCheckInterval
resource.loader.modificationCheckInterval属性用于指定缓存资源的修改信息检测时间间隔，用秒计算。这个属性仅仅在其相应的resource.loader.cache属性为true时才有意义。当属性质为负数时，将完全禁止检测功能。velocity.properties文件为file.resource.loader.modificationCheckInterval属性提供了一个值：2。
Miscellaneous

5.其他

下面的属性将影响Velocity运行时行为的混杂样子（miscellaneous aspects）。

runtime.interpolate.string.literals
runtime.interpolate.string.literals属性用于指定是否允许模板引擎窜改字符串。受到影响的包括#set指令等号（=）右边的用双引号引起来的字符串、引用方法的参数、Velocimacro参数和其他Velocity指令的普通参数。如果这个属性的值为false，这样的字符串将被当成单引号引起来的字符串对待，从不被窜改。默认值为true。

parser.pool.size
parser.pool.size属性用于指定运行时启动时创建的解析器池大小。这个属性设置的是最小值，如果需要增加额外的解析器，并超过了设定值，则系统会自动创建，但这些新创建的不会增加到池中，用完即扔。默认值为20。

Resource Loaders
在讨论Velocity属性的时候，我们介绍了许多可能影响资源加载的属性，而不需要真正为资源加载定义什么。简而言之(Here we rectify that omission)，Velocity resource可以简单理解为模板引擎的输入（omission. A Velocity resource is simply an input to the template engine）。这样的输入包括正规模板、Velocimacro库和#include指令导入的纯文本。
一个resource loader就是一个简单的实体，主要用于从特定的源里获取这样的资源。迄今为止，所有的示例都依赖Velocity的文件资源加载器，它通过FileResourceLoader类来实现。同样地，其默认属性在我们讨论Velocity资源管理的文件资源加载器配置的时候就已经研究过了。然而，除了创建定制的资源加载器之外，Velocity也完全支持其他三种类型的资源加载器：JAR、Classpath和DataSource。
JAR资源加载器是通过Velocity的JarResourceLoader类来实现的，用于从JAR文件获取资源。我们描述的这个文件资源加载器属性可用于JAR资源加载，除了可用于外，resource.loader.path属性使用带有异常的JAR URL语法加载JAR资源，关于这个语法的更多信息，见Java的JarURLConnection类文档。

Classpath资源加载器是通过Velocity的ClasspathResource-Loader类实现的，通过CLASSPATH资源里的ClassLoader来获取资源。这个资源可以是zip文件、JAR文件或目录。在和servlets一起工作时，这个资源加载器特别有用。资源加载器属性相关的加载器是resource.loader.description和resource.loader.class，但只有resource.loader.class是必需的。

DataSource资源加载器是通过Velocity的DataSourceResourceLoader类实现的。通过从Java DataSource对象获得的物理数据源连接来获取资源。一个明显的例子就是从一个关系数据库里获得Velocity模板和相关的资源的情况。这个资源加载器除了resource.loader.path以外，可以使用所有的资源加载器属性。这个加载器还唯一支持几个其他的属性。关于这个属性的更多相关信息，可查阅Velocity的API文档DataSourceResourceLoader类。这个资源加载器需要J2EE，还不能被标准Velocity构建包包含。