p>?基礎

Configuration 是一個存放應用級別（application level）公共配置信息，以及模版（Template）可使用的全局共享變量的一個對象。同時它還負責模版（Template）實例的創(chuàng)建以及緩存。Configuration 實際上是freemarker.template.Configuration?對象的實例，使用其構造函數(shù)創(chuàng)建。通常應用使用一個共享的單實例Configuration 對象。

Configuration 對象可被Template 對象的方法使用，每一個模版實例都關聯(lián)與一個Configuration 實例，它是通過Template 的構造函數(shù)被關聯(lián)進去的，通常是你使用這個方法來Configuration.getTemplate?獲得模版對象的。

共享變量

共享變量是那些定義給所有模版（Template）使用的變量。你可以通過configuration對象的setSharedVariable?方法來添加共享變量。

Configuration cfg = new Configuration(); ... cfg.setSharedVariable("wrap", new WrapDirective()); cfg.setSharedVariable("company", "Foo Inc."); // Using ObjectWrapper.DEFAULT_WRAPPER

所有與該configuration 對象關聯(lián)的模版實例都就可以通過獲得to_upper?轉換器，company?來獲得字符串，因此你不需要再一次次的往root 中添加這些變量了。如果你往root 添加同名的變量，那么你新添加的變量將會覆蓋之前的共享變量。

警告！

如果configuration 對象被多線程調用，那么不要使用TemplateModel 實現(xiàn)類作為共享變量，因為他們是非線程安全的，例如基于servlet 的web 站點就是這種情況。

Configuration 對象初始化時已經(jīng)包含一些共享轉換器變量:

名字類

name class capture_output freemarker.template.utility.CaptureOutput compress freemarker.template.utility.StandardCompress html_escape freemarker.template.utility.HtmlEscape normalize_newlines freemarker.template.utility.NormalizeNewlines xml_escape freemarker.template.utility.XmlEscape?

配置參數(shù)

配置參數(shù)是那些可以影響FreeMarker 運行行為的那些命名參數(shù)。例如locale,number_format。

配置參數(shù)存儲在Configuration實例中，它可以被模版實例（Template）修改。例如，你在Configuration中設置了locale等于"en_US"，那么所有的模版對象都會使用，"en_US"除非你在單個模版實例中利用setLocale方法修改了默認配置。因此configuration設置的參數(shù)可以當作是默認參數(shù)，它可以被Template一級設置的參數(shù)覆蓋，而它們兩者設置的參數(shù)信息又可以被環(huán)境中設置的參數(shù)所覆蓋（也就是模版文件指令設置的）如下：

${1.2}<#setting locale="en_US">${1.2}

這種調用方式你可以想象成3 個層（配置對象層，模版層，運行環(huán)境層）下面表格中顯示了每一層對于參數(shù)的設置：

Setting A Setting B Setting C Setting D Setting E Setting F Layer 3:Environment 1 - - 1 - - Layer 2:Template 2 2 - - 2 - Layer 1:Configuration 3 3 3 3 - -

那么配置參數(shù)的最終結果分別是：A = 1, B = 2, C = 3, D = 1, E = 2.而F 參數(shù)很可能就是null。

如果要查詢可設置的參數(shù)列表，你可以查閱FreeMarker API 文檔的以下兩個部分：
所有層的配置

freemarker.core.Configurable.setSetting(String, String)

Coniguration 層的配置

freemarker.template.Configuration.setSetting(String,String)

加載模板

模版加載器

模版加載器是基于抽象路徑（"index.ftl"或"products/catalog.ftl"）加載原始數(shù)據(jù)的那些對象，而究竟加載何種資源（目錄中的文件數(shù)據(jù)還是數(shù)據(jù)庫中的數(shù)據(jù)）取決于具體的加載器實現(xiàn)。當你調用cfg.getTemplate?時，F(xiàn)reeMarker 將會詢問你之前配置給Configuration 對象的模版加載器，有該模版加載器負責文件的載入。

內建的模版加載器
你可以用以下三個方法來設置模版加載的三種方式

void setDirectoryForTemplateLoading(File dir);

或者

void setClassForTemplateLoading(Class cl, String prefix);

或者

void setServletContextForTemplateLoading(Object servletContext, String path);

以上第一種方式顯示的指定了一個文件系統(tǒng)中的目錄，F(xiàn)reeMarker 將會在此目錄記載模版，不用說，此目錄必須存在，否在會拋出異常。

第二種方式以一個Class作為一個輸入?yún)?shù)，當你想使用ClassLoader的方式來加載模版的時候，你就可以使用這種方式，這種方式將會調用來尋找模版文件，同時這種模版加載的方式要比前一種穩(wěn)定一些尤其是在生產(chǎn)系統(tǒng)中。你可以很容易的把資源文件，以及圖標等打包到.jar 文件中。

第三種方式把web 應用的上下文以及基路徑（相對與WEN-INF 的父路進來說）作為參數(shù)。該種方式的模版加載器將會從web 應用上下文種加載模版。

從多個位置加載模版

如果你想從多個位置加載模版的話，你可以分別創(chuàng)建與不同位置對應的單個模版加載器，然后把它們包裹到一個名叫MultiTemplateLoader模版加載器中，最終通過方法setTemplateLoader(TemplateLoader loader)把其設置給Configuration 對象，以下有一個從兩個不同位置加載模版的例子：

import freemarker.cache.*; // template loaders live in this package ... FileTemplateLoader ftl1 = new FileTemplateLoader(new File("/tmp/templates")); FileTemplateLoader ftl2 = new FileTemplateLoader(new File("/usr/data/templates")); ClassTemplateLoader ctl = new ClassTemplateLoader(getClass(), ""); TemplateLoader[] loaders = new TemplateLoader[] { ftl1, ftl2, ctl }; MultiTemplateLoader mtl = new MultiTemplateLoader(loaders); cfg.setTemplateLoader(mtl);?

FreeMarker 將會首先在路徑/tmp/templates中搜索模版文件，如果沒有找到那么回到路徑/usr/data/templates中搜索，如果還沒有找到，那么則會嘗試用class-loader的方式加載。

從其他資源中獲取模版文件

如果在這些內建的模版加載器中沒有一個符合你的要求，那么你可以自己定制一個模版加載器，只需要實現(xiàn)freemarker.cache.TemplateLoader?接口就可以了，然后通過方法setTemplateLoader(TemplateLoader loader)把其傳遞給Configuration對象。

緩存模版

FreeMarker緩存模版的意思就是，當你通過getTemplate方法獲取一個模版的時候，F(xiàn)reeMarker不僅會返回一個Template對象，而且會緩存該對象，當你下一次以相同的路徑請求模版的時候，它就會返回緩存中的模版對象。如果你改變了模版文件，那么當你下一次獲取模版的時候，F(xiàn)reeMarker會自動重新加載，重新解析模版。雖然如此，但是如果直接判斷一個文件是否修改過是一個耗時的操作，那么FreeMarker 在Configuration 對象級別提供了一個配置參數(shù)“update delay”。該參數(shù)的意思是FreeMarker多長時間去判斷一次模版的版本，默認設置是5秒鐘，也就是每個5秒就會判斷模版是否經(jīng)過修改，如果你想實時的判斷，那么設置該參數(shù)為0。另外一點需要注意，并不是所有的加載器都支持這種判斷方式，舉例來說基于class-loader 的模版加載器就不會發(fā)現(xiàn)你修改過模版文件。

對于刪除緩存中的模版FreeMarker 是這么做的，你可以使用Configuration 對象方法clearTemplateCache?以手工的方式清楚緩存中的模版對象。而實際上緩存部分可以作為一個組建加入到FreeMarker 中（也就是它可以使用第三方緩存方案）你可以通過設置cache_storage?這個參數(shù)來實現(xiàn)。對大多數(shù)開發(fā)者來FreeMarker 自帶的freemarker.cache.MruCacheStorage?實現(xiàn)已經(jīng)足夠了。這個緩存使用2 個級別的Most Recently Used（最近最多用）策略。在第一個級別，所有的緩存條目都是使用強引用（strongly referenced：條目并不會被JVM 所清楚，與其相對的弱引用softly reference）直到達到最大時間，那些最近最少使用的條目就會被遷移到二級緩存。在這個級別條目都是使用弱引用直到達到過期。若引用與強引用的區(qū)域的大小是可以在構造函數(shù)中設置的，例如你想把強引用區(qū)域設置為20，弱引用區(qū)域設置為250，那你可以使用以下代碼：

cfg.setCacheStorage(new freemarker.cache.MruCacheStorage(20, 250))

由于MruCacheStorage 是默認的緩存實現(xiàn)，那么你也可以這樣設置：

cfg.setSetting(Configuration.CACHE_STORAGE_KEY,"strong:20, soft:250");

當你創(chuàng)建一個新的Configuration時，其默認使用MruCacheStorage緩存實現(xiàn)且默認的值maxStrongSize等于0，maxSoftSize等于Integer.MAX_VALUE（也就是理論最大值）。但是對于高負荷的系統(tǒng)來說，我們建議maxStrongSize?設置成一個非0 的數(shù)值，不然會導致頻繁的重新加載，重新解析模版。

異常處理

可能產(chǎn)生的異常

FreeMarker 產(chǎn)生的異常一般可歸以下幾類：

FreeMarker 初始化階段產(chǎn)生的異常： 通常在你的應用中僅需要初始化FreeMarker 一次，而當在這個時間段類產(chǎn)生的異常就叫做初始化異常。

加載解析模版期的異常：當你通過Configuration.getTemplate()方法獲取模版的時候（如果模版之前沒有被緩存），將會產(chǎn)生兩類異常：

IOException：由于模版沒有找到，或在讀取模版的時候發(fā)生其他的IO異常，比如你沒有讀取該文件的權限等等； freemarker.core.ParseException 由于模版文件的語法使用不正確；

執(zhí)行期間的異常：當你調用Template.process(...)方法的時候，會拋出兩類異常：

IOException 往輸出寫數(shù)據(jù)時候發(fā)生的錯誤； freemarker.template.TemplatException其他運行期產(chǎn)生的異常，比如一個最常見的錯誤就是模版引用了一個不存在的變量；

更多FreeMarker配置(Configuration)相關文章請關注PHP中文網(wǎng)！