FreeMarker配置(Configuration)

p> 基本

Configuration は、テンプレートで使用できるアプリケーション レベルのパブリック構成情報とグローバル共有変数を保存するオブジェクトです。同時に、テンプレート インスタンスの作成とキャッシュも行います。 Configuration は、実際には、コンストラクターを使用して作成された freemarker.template.Configuration オブジェクトのインスタンスです。通常、アプリケーションは共有の単一インスタンスの構成オブジェクトを使用します。

Configuration オブジェクトは、Template オブジェクトのメソッドで使用できます。各テンプレート インスタンスは、Template のコンストラクターを介して関連付けられます。通常、このメソッドを使用して、Configuration.getTemplate を通じてテンプレート オブジェクトを取得します。

共有変数

共有変数は、すべてのテンプレートで使用するために定義された変数です。構成オブジェクトの setSharedVariable メソッドを通じて共有変数を追加できます。

Configuration cfg = new Configuration(); ... cfg.setSharedVariable("wrap", new WrapDirective()); // ObjectWrapper.DEFAULT_WRAPPER を使用します

構成オブジェクトに関連付けられたすべてのテンプレート インスタンスは、to_upper コンバーターと会社を取得することで文字列を取得できるため、これらの変数をルートに何度も追加する必要はありません。同じ名前の変数を root に追加すると、新しく追加された変数によって以前の共有変数が上書きされます。

警告!

構成オブジェクトが複数のスレッドによって呼び出される場合は、TemplateModel 実装クラスを共有変数として使用しないでください。サーブレットベースの Web サイトの場合のように、TemplateModel 実装クラスはスレッドセーフではないためです。

Configuration オブジェクトには、初期化時にいくつかの共有コンバーター変数がすでに含まれています:

name class

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

設定パラメータ

設定パラメータは、FreeMarker の実行動作に影響を与える可能性のある名前付きパラメータです。たとえば、locale、number_format。

設定パラメータは設定インスタンスに保存され、テンプレート インスタンス (Template) によって変更できます。たとえば、設定でロケールを「en_US」に設定した場合、単一のテンプレート インスタンスで setLocale メソッドを使用してデフォルト設定を変更しない限り、すべてのテンプレート オブジェクトは「en_US」を使用します。したがって、構成によって設定されたパラメータはデフォルトのパラメータと見なすことができ、テンプレート レベルによって設定されたパラメータによって上書きでき、それらによって設定されたパラメータ情報は環境に設定されたパラメータによって上書きできます（つまり、テンプレート ファイルの指示によって設定) 以下のように:

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

この呼び出しメソッドは 3 つの層 (構成オブジェクト層、テンプレート層、実行環境レイヤー) 以下の表に示すように、各レイヤーのパラメーター設定は次のとおりです。

設定 A 設定 B 設定 C 設定 D 設定 E 設定 F レイヤー 3:環境 1 - - 1 - - レイヤー 2:テンプレート 2 2 - - 2 - Layer 1:Configuration 3 3 3 3 - -

すると、構成パラメータの最終結果は次のようになります: A = 1、B = 2、C = 3、D = 1、E = 2。F パラメータは次のとおりです。 null である可能性があります。

設定可能なパラメータのリストをクエリしたい場合は、FreeMarker API ドキュメントの次の 2 つの部分を参照してください:
すべてのレイヤーの構成

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

構成レイヤーの構成

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

テンプレートの読み込み

テンプレートローダー

テンプレートローダーは、抽象パス (「index.ftl」または「products/catalog.ftl」) に基づいて生データを読み込みます) これらのオブジェクト、およびどのリソースがロードされるか (ディレクトリ内のファイル データまたはデータベース内のデータ) は、特定のローダーの実装によって異なります。 cfg.getTemplate を呼び出すと、FreeMarker は、Configuration オブジェクトに対して以前に構成したテンプレート ローダーを要求します。テンプレート ローダーは、ファイルをロードします。

組み込みのテンプレートローダー
次の 3 つのメソッドを使用して、テンプレート読み込みの 3 つのメソッドを設定できます

void setDirectoryForTemplateLoading(File dir);

or

void setClassForTemplateLoading(Class cl, String prefix);

Or

void setServletContextForTemplateLoading(Object servletContext, String path);

上記の最初のメソッドは、ファイル システム内のディレクトリを明示的に指定します。言うまでもなく、FreeMarker はこのディレクトリにテンプレートを記録する必要があります。そうでない場合は例外が発生します。投げられた。

2 番目のメソッドは、ClassLoader を使用してテンプレートをロードする場合、このメソッドを使用してテンプレート ファイルを検索します。この方法は、特に運用システムにおいて、以前の方法よりも安定しています。リソース ファイル、アイコンなどを .jar ファイルに簡単にパッケージ化できます。

3 番目のメソッドは、Web アプリケーションのコンテキストとベース パス (WEN-INF の親パスに対する相対パス) をパラメーターとして受け取ります。このスタイルのテンプレート ローダーは、Web アプリケーション コンテキストからテンプレートを読み込みます。

複数の場所からテンプレートをロードする

複数の場所からテンプレートをロードしたい場合は、異なる場所に対応する個別のテンプレート ローダーを作成し、それを MultiTemplateLoader という名前のテンプレート ローダーにラップします。最後に、それを Configuration オブジェクトに設定します。 setTemplateLoader(TemplateLoaderloader) メソッド。 2 つの異なる場所からテンプレートをロードする例を次に示します。

import freemarker.cache.*; // テンプレート ローダーはこのパッケージに存在します ... 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);

FreeMarker は、パス /tmp/templates でテンプレート ファイルを検索します。見つからない場合は、パス /usr/data/templates に戻って検索します。まだ見つからない場合は、class-loader を使用してロードを試みます。

他のリソースからテンプレート ファイルを取得する

これらの組み込みのテンプレート ローダーが要件を満たしていない場合は、freemarker.cache.TemplateLoader インターフェイスを実装して、それを設定に渡すだけでテンプレート ローダーをカスタマイズできます。 setTemplateLoader(TemplateLoaderloader) メソッドを通じてオブジェクトを取得します。

テンプレートのキャッシュ

FreeMarker のテンプレートのキャッシュとは、getTemplate メソッドを通じてテンプレートを取得すると、FreeMarker が Template オブジェクトを返すだけでなく、次回同じパスでテンプレートをリクエストしたときにそのオブジェクトをキャッシュすることを意味します。キャッシュ内のテンプレート オブジェクトを返します。テンプレート ファイルを変更すると、次回テンプレートを取得したときに、FreeMarker は自動的にテンプレートをリロードして再解析します。それでも、ファイルが変更されたかどうかを直接判断するのが時間のかかる操作である場合、FreeMarker は、Configuration オブジェクト レベルで構成パラメータ「更新遅延」を提供します。このパラメータは、FreeMarker がテンプレートのバージョンを判断するのにかかる時間を意味します。デフォルト設定は 5 秒です。つまり、テンプレートが変更されたかどうかを 5 秒ごとに判断します。リアルタイムで判断したい場合は、これを設定します。このパラメータを 0 に設定します。もう 1 つの注意点は、すべてのローダーがこの判定方法をサポートしているわけではないことです。たとえば、クラスローダーに基づくテンプレート ローダーでは、テンプレート ファイルが変更されたことが検出されません。

これは、FreeMarker がキャッシュ内のテンプレートを削除する方法です。Configuration オブジェクトのメソッド、clearTemplateCache を使用して、キャッシュ内のテンプレート オブジェクトを手動でクリアできます。実際、キャッシュ部分はコンポーネントとして FreeMarker に追加できます (つまり、サードパーティのキャッシュ ソリューションを使用できます)。これは、cache_storage パラメーターを設定することで実行できます。ほとんどの開発者にとって、FreeMarker に付属する freemarker.cache.MruCacheStorage 実装で十分です。このキャッシュは、2 レベルの最近使用したポリシーを使用します。第 1 レベルでは、最大時間に達するまですべてのキャッシュ エントリが強参照され (ソフト参照ではなく、エントリは JVM に認識されません)、最も最近使用されていないエントリは第 2 レベルのキャッシュに移行されます。このレベルのエントリは、有効期限が切れるまで弱い参照を使用します。参照領域と強参照領域のサイズをコンストラクターで設定できる場合、たとえば、強参照領域を 20 に、弱参照領域を 250 に設定したい場合は、次のコードを使用できます:

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

MruCacheStorage はデフォルトのキャッシュ実装であるため、次のように設定することもできます:

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

新しい構成を作成すると、デフォルトで MruCacheStorage キャッシュ実装が使用され、デフォルト値 maxStrongSize は 0、maxSoftSize は Integer.MAX_VALUE (理論上の最大値) に等しくなります。ただし、高負荷システムの場合は、maxStrongSize を 0 以外の値に設定することをお勧めします。そうしないと、テンプレートの再読み込みと再解析が頻繁に発生します。

例外処理

発生する可能性のある例外

FreeMarker によって生成される例外は、一般に次のカテゴリに分類できます:

FreeMarker の初期化フェーズ中に生成される例外: 通常、FreeMarker を初期化する必要があるのは、アプリケーション内で 1 回だけです。この期間中にクラスによって生成される例外は初期化例外と呼ばれます。

テンプレートの読み込みおよび解析中の例外: Configuration.getTemplate() メソッドを通じてテンプレートを取得するとき (テンプレートが以前にキャッシュされていない場合)、2 種類の例外が発生します:

IOException: テンプレートが見つからないため、またはテンプレート ファイルの構文が間違っているため、ファイルを読み取る権限がないなどの他の IO 例外が発生します。

期間中の例外の実行: Template.process(...) メソッドを呼び出すと、次の 2 種類の例外がスローされます:

IOException 出力にデータを書き込むときに発生するエラー; freemarker.template.TemplatException 生成されるその他の例外たとえば、最も一般的な間違いの 1 つは、テンプレートが存在しない変数を参照していることです。

FreeMarker 構成 (構成) 関連の記事については、PHP 中国語 Web サイトに注目してください。