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構建包包含。