Velocity は、Java に基づくテンプレート・エンジンであり、あなたのデータをフォーマットしたり表示したりするために、文書をレンダリングしたり容易に作成するための単純で強力な開発ツールです。 このガイドでは、Velocity を使用した開発の基本概要について説明していきます。 そして、Velocityの使い方のために2つの主な使い方に焦点を当てます：
Velocity を使ってあなたのサーブレットでクラスに基づいた VelocityServlet クラスを 使って非常に簡単にサーブレットを開発すること、役に立つユーティリティクラスを 使用してアプリケーション開発をすることに関して、あなたは、これらの間に本質的な 違いはないということが分かると思います。
はじめに
この情報は Velocity サイトの上やドキュメントの中のどこか他の場所で見つけられるかもしれませんが、それは完全にここに含まれています。 Velocity をあなたのコンピュータで実行するのは、非常に簡単です。 全てのディレクトリの参照は Velocity 配布ツリーのルートの相対パスに注意してください。
build ディレクトリに移動します。
ant <build target> とタイプします。ここで <build target> は以下のうちのひとつです。
jar bin ディレクトリに Velocity
の完全版を構築します。jar は、'velocity-X.jar' と呼ばれます。
ここで「X」は、現在のバージョン番号です。
あなたに特定の格納場所に対する配慮が必要ない限り、
それはあなたが必要とするすべてを含むので、
この jar を使うのが便利です。
jar-nodeps は、完全な Velocity jar を bin
ディレクトリにビルドします。ただし必要なロギングサポート
Jakarta Commons の
Jakarta
Avalon Logkit パッケージや、WebMacro テンプレート変換で必要となる
Jakarta ORO
パッケージは含まれません。このターゲットを使用する場合には、
Jakarta Common のコレクションコンポーネントの jar を取得して
CLASSPATH(またはWEB-INF/lib) に追加しなければなりません。
また、組み込みロギングやテンプレート変換を使用したい場合には、
あなたの CLASSPATH または Web アプリケーションの WEB-INF/lib ディリクトリに jar
を置いてください。
jar-core
bin ディレクトリにサイズの小さな「velocity-core-X.jar」という名前の
Velocity jar を構築します。この jar には、Velocity 機能のコアが含まれていますが、
例、Anakia、Texen のようなユーティリティや、
VelocityServer をサポートする基本クラスは含まれていません。
jar-util
はユーティリティ Velocity jar を bin ディレクトリに構築します。
そして、「velocity-util X.jar」と呼ばれています。
この jar は、ユーティリティ・コード、特に Anakia、Texen と WebMacro テンプレート変換ユーティリティを含みます。
jar-servlet
はユーティリティ Velocity jar を bin ディレクトリに構築します。
そして、「velocity-servlet X.jar」と呼ばれています。
この jar は、servlet プログラマーのためのユーティリティ・コードを含みます。
jar-j2ee は、
J2EE サポートを必要とするすべてのコンポーネントを含む「jar」ターゲットの様に、
完全な jar を構築します。
現在、これは org.apache.velocity.runtime.resource.loader.DataSourceResourceLoader だけを含みます。
通常通り、それは bin ディレクトリに置かれます。そして、「velocity-j2ee-X.jar」と呼ばれています。
注意：
この構築ターゲットを使用したいときには、build/lib ディレクトリに j2ee.jar
のコピー(またはリンク)を置かなければなりません。
我々は、配布の一部としてそれを提供していません。
よい情報源 http://java.sun.com/ にあります。
jar-J2EE-nodeps は、
J2EE サポートの完全な jar をビルドしますが、Jakarta Avalon Logkit と
Jakarta ORO パッケージの regexp サポートを除外します。
上記のjar-nodeps ターゲットを参照してください。
examplesは
examples ディレクトリで見つけられるプログラム例のコードを構築します。
これは、ターゲットがまた、forumdemo プロジェクト例を構築します。
forumdemo は、サンプル Web アプリケーションを
examples/forumdemo ディレクトリに構築します。
docs は、
Velocity の Anakia XML 変換ツールを使用して
これらのドキュメントを docs ディレクトリに構築します。
スタイルシートの代わりに Velocity テンプレートを使うことができます。
−試してみてください！
注：
このターゲットは、jakarta-site2 プロジェクトが jakarta-velocity 配布ディレクトリと同じディレクトリとして位置することを必要とします。
このターゲットについての詳細は build.xml ファイルを見てください。
jar-src は、
全ての Velocity ソース・コードを一つの jar にまとめます。
そして、bin ディレクトリに置かれます。
javadocs は
docs/api ディレクトリにおいて、Javadoc クラス・ドキュメントを構築します。
test (jar のあとで)それに対する Velocity
テストルーチンの testbed セットに対してテストを行ないます。
help 利用できる構築ターゲットの一覧を表示します。
test ターゲットを使ってください。
ant examples を通して例を構築してください。
多くのリソースと利用できる例がプログラマーに用意してあります、 そして、我々はあなたが我々の例と、ドキュメントとソース・コードを見ることをお勧めします。 素晴らしいソースの一部は、以下の通りです
src/java/... : Velocity プロジェクトのすべてのソースコードがあります。
examples/app_example1 :
アプリケーションプログラムで、Velocity をどのように使うか示した簡単な例
examples/app_example2 :
Velocity アプリケーション・ユーティリティクラスを使用したアプリケーションプログラムの簡単な例
examples/servlet_example1 :
サーブレットで Velocity を使用する方法を示した簡単な例
examples/logger_example :
全てのログメッセージを受信するために Velocity を使ってカスタムログを作成して登録する
簡単な例
examples/xmlapp_example :
Velocity テンプレートを使用して XML ドキュメントデータへのアクセスと読み込むために
JDOM の使い方の簡単な例。ドキュメントツリーを渡り歩くための Velocimacro
の再帰のデモも含まれます。
examples/event_example :
Velocity 1.1 の API でイベントハンドリングを使った例
examples/anakia :
XML データのレンダリングのスタイルシートを生成するために Velocity
を使ったアプリケーションの例
examples/forumdemo :
サーブレットベースのフォームアプリケーションの動作例
docs : Velocityプロジェクトのために
html で生成されたすべてのドキュメント
docs/api :
Velocity プロジェクトのために生成された Javadoc ドキュメント
test/templates :
テストベッドディレクトリ内のテンプレートの大きな集合で、
VTL(Velocity Template Language) の使い方のすばらしいソースがあります。
examples/context_example :
Velocity context を拡張することのできる2つの例があります。
上級者向け。
上の全てのディレクトリの参照は、配布ルートディレクトリの相対パスです。
アプリケーションプログラムやサーブレットで Velocity を使う場合 (または正確にはその他の場合も)、以下のことを行なう必要があります。
org.apache.velocity.app.Velocity
クラスを経由でシングルトンパターンを使用するには、
コードでは、このようになります。
これが、基本的なパターンです。 とっても単純ですね？ これは、通常あなたがテンプレートをレンダリングするのに Velocity を使うときに行なうことです。 あなたは多分必ずしもこのようにコードを書くことにはならならないでしょう−我々は servlet とアプリケーション・プログラマーの双方に対して、より簡単にするための 2 〜 3 のツールを用意しています。 このガイドの中で後ほど、我々は両方のサーブレットで一般的なアプリケーションと同様に Velocity を使うことについて説明します、そして、我々は我々がより簡単にするために提供するツールを検討します。 どちらの場合も上記のシーケンスがその舞台裏で動いているのは事実です。
Velocity 1.2 からは、Velocity エンジンを使うにあたって、開発者は シングルトンモデルかインスタンスモデルの分離の 2 つの選択肢があります。 どちらの方法も同じ Velocity コードのコアを使用し、 Velocity をより簡単にあなたの Java アプリケーションに統合することができます。
これは、レガシーなパターンですべての JVM(またはWebあぶりケーション依存) でひとつの
Velocity エンジンのインスタンスが共有されます。
これはリソースの共有とローカライズされた設定のためにはとても便利な方法です。
例えば、これはサーブレット 2.2 以降に互換の Web アプリケーションで使用するためには適切なモデルで、それぞれの Web アプリケーションは、独自の Velocity のインスタンスを持ち、
Web アプリケーションのサーブレットは、テンプレート、ログ、その他のリソースを共有します。
シングルトンは、org.apache.velocity.app.Velocity クラスからアクセス
することができ、以下のように使用します。
シングルトンモデルは、
org.apache.velocity.servlet.VelocityServlet ベースクラスで
使用され、ユーティリティクラスは、サーブレットを簡単に作成するために
配布されることに注意してください。
このクラスを拡張することは Velocity を使っている servlets
を書く最も共通で便利な方法ですが、
あなたが別な目的のためにこのクラスを使わないのは自由です。
バージョン 1.2 から、あなたは、同じJVM(またはWebアプリケーション)
で Velocity のインスタンスを多く
使用して、インスタンスを別々に作成し、設定することができます。これは、
テンプレートディレクトリや、ログ、その他を同じアプリケーションで
設定を分割したいときに役立ちます。分割インスタンスを使用するためには、
org.apache.velocity.app.VelocityEngine クラスを使用します。
上記のシングルトンの例と似たような例があります。
ごらんのように、これはとてもシンプルで簡単なものです。 幾つかの単純な文法の変更で、 Velocity をシングルトンやインスタンス分割の要求のためにあなたのアプリケーションやテンプレートの高レベルの構造は変更する必要はありません。
プログラマーとして、クラスは、Velocity 内部と影響しあうものは、
もしシングルトンモデルを使用する場合には、
org.apache.velocity.app.Velocity で、
シングルトンモデル以外(「分割インスタンス」)を使用する場合には、
org.apache.velocity.app.VelocityEngine です。
アプリケーションで
org.apache.velocity.runtime パッケージにある
内部の
Runtime, RuntimeConstants,
RuntimeSingleton or RuntimeInstance クラスを
決して使わないでください。これらは内部使用のみを想定しており、そのうち変更されます。
上で言及されるように、あなたが使うはずであるクラスは org.apache.velocity.app
パッケージにある、Velocity と VelocityEngine クラスです。
何かが見つからないか、それらのクラスから必要ならば、
変更点を提案するのをためらわないでください−これらのクラスはアプリケーション開発者を対象とします。
『コンテキスト』の概念は、Velocity にとって主要で、 システムの一部の間でデータのコンテナをまわりに移動することの共通のテクニックです。 その考え方は、コンテキストが Java 層の間のデータの『キャリヤー』であるということです（あるいは、あなたプログラマー）、そして、テンプレート層（またはデザイナー）。 プログラマーとしてのあなたは、いろいろなタイプ（あなたのアプリケーションが要求するものは何でも）のオブジェクトを集めることになって、コンテキストでそれらを置くことになります。 デザイナー、これらのオブジェクトと彼らのメソッドに、そして、プロパティは references と呼ばれているテンプレート要素を通してアクセス可能になることになります。 通常、あなたはデータがアプリケーションのために必要とすると決定するデザイナーと働くことになります。 ある意味では、あなたがテンプレートでアクセスにデザイナーに設定されるデータを生産するので、これは『API』になることになります。 したがって、開発プロセスのこのフェーズで、それは若干の時間と慎重な分析を捧げる価値があります。
Velocity がサポート特別なニーズとテクニック（直接（例えば）LDAP サーバーにアクセスするコンテキストのような）にあなた自身のコンテキスト・クラスを作成するためにあなたを許すが、VelocityContext と呼ばれている良い基本の実装クラスは配布の一部としてあなたに対して用意されています。
VelocityContext は全ての一般的な目的ニーズにふさわしいです、 そして、我々はあなたがそれを使うことを強く推奨します。 例外的で高度な利用の場合のみ、あなたがあなた自身のコンテキスト実装を拡張するか、 つくる必要があります。
VelocityContext を使うことは、標準的な Java Hashtable なクラスを使用するのと、 同じくらい単純です。 インタフェースが他の役に立つメソッドを含むが、あなたが使うことになる 2つの主なメソッドはあります
Hashtable と同じように注意してください、値は java.lang.Object から派生しなければならず、 null ではいけません。 int または float のような基本タイプは、適切なラッパー・クラスで包まれなければなりません。
それは、実際には全てが基本のコンテキスト操作にあります。 詳細は、配布に含められる API ドキュメンテーションを見てください。
Support for Iterative Objects for #foreach()
プログラマーとして、あなたがコンテキストに置いたオブジェクトにおいて、
あなたは素晴らしい自由があります。
しかし、大部分の自由と同様に、これはほんの少しの責任もあるので、
Velocity がサポートするものと起こるかもしれないどんな生成物でも理解してください。
Velocity は、VTL #foreach() 指示子のために、
いくつかの適当なコレクション・タイプをサポートします。
Object [] 規則的なオブジェクト配列（ここで言われる多くの必要でない）。
Iterator インタフェースを提供するクラスで、
Velocity は内部であなたの配列を包むことになります、しかし、
それはプログラマーまたはテンプレート著者としてあなたに関係するはずではありません。
java.util.Collection あなたがあなたのオブジェクトでコレクション・インタフェースを実装しているならば、Velocity はループにおいて使う Iterator をそうようにするために iterator() メソッドを使用することになります、
iterator() が働く Iterator を返すことを確認してください。
java.util.Map ここでは、Velocity は Collection
インタフェースを得るためにインタフェースの values() メソッドに依存します。
そこでは、iterator() はループのために Iterator を取り出すために呼ばれます。
java.util.Iterator 使用上の注意:
これは仮に現在サポートされるだけです−重要性の問題は Iterator の「非 resettablity」です。
『裸の』Iterator がコンテキストに置かれて、Iterator としての1つの #foreach()
（第一の後のブロックが失敗することになる以降の #foreach()）がリセットしないより、
多くのものにおいて使われる。
java.util.Enumeration の使用上の注意：
java.util.Iterator の様に、これは仮に現在サポートしているだけです−
重要性の問題は列挙の『非resettablity』です。
『裸の』列挙がコンテキストに置かれて、列挙としての1つの #foreach()（第一の後のブロックが失敗することになる以降の #foreach()）がリセットしないより、多くのものにおいて使われる。
Iterator と Enumeration の場合、
それが避けられることができないときだけ、彼らがコンテキストで置かれることは推薦されます、
そして、それが十分で可能なとき、あなたは Velocity
を適切な再使用できる反復的なインタフェースを見つけさせるはずです。
直接 java.util.Iterator インタフェース
（例えば、JDBC を経由の大きなデータ・セット）を使用する良い理由があります、
しかし、それが避けられることができるならば、何か他を使うよりよいかもしれません。
『直接』に、我々は何かをすることを意味しました：
ここで、Iterator がコンテキストに置かれるところ。 その代わりに、あなたが単に行います：
それから、全ては洗練された：
Velocity はその（リスト経由で）Vector 実装コレクションを理解して、したがって、
iterator() メソッドを見つけることになります、そして、
各時その使用のために『新しい』Iterator のためにそれを得るそれが必要とする使用はそうします。
普通の Iterator だけで（...より上の最初の切れっぱし）一旦 velocity が
#foreach() でそれを使うならば、Velocity にはそれが使われる次の
#foreach() の用途に、新しいものを得ることの方法がありません。
結果は、そのリファレンスを使っている少しの以降の #foreach()
ブロックからもの出力ではありません。
上のこれは、Velocity でコレクションについて繰り返すことは素晴らしい心配を必要として、 考えた何かであるという印象を与えるはずではありません。 むしろ、一般に、正反対は真実です。 あなたがコンテキストに Iterator を置くとき、慎重にするだけでください。
Context ChainingVelocity のコンテキスト・デザインの革新的な機能は、context chaining の概念です。 また、時々 context wrapping と呼ばれて、この先進の機能は、 それをテンプレートに1つの「隣接する」コンテキストとして現れさせる方法において、 一緒に別々のコンテキストを接続するためにあなたを許します。
これは、例で一番良く示されます：
上のコードにおいて、我々は上に向かう context2 にそれが context1 を chains するようなものを課しました。 テンプレートでのそれ、あなたがそうすることができるこの手段少しもオブジェクトを加えるために使われるキーの重複がない限り、2つの VelocityContext オブジェクトのどちらにでも入れられたアイテムのアクセス。 それが場合であるならば、そのままに重要な「複製」のためにより上に、 チェーンにおいて最も近いコンテキストで保存されるオブジェクトは利用できることになります。 上のこの例で、オブジェクトは「I am in context2」という文字列が返される。
この重複または「covering」がコンテキスト・アイテムの少しの方法にもおいてしないという注意は、おおわれたオブジェクトを害するか、変えます。 上の例でそうストリング「私は、context1でいます」生きてよくcontext1.get("duplicateを通してさらにaccessableである」）。 上の例で以外、テンプレートでのリファレンス『$duplicate』の値はす『私は、context2でいます』、そして、テンプレートはおおわれたひもにアクセスをしません『私は、context1でいます』。
あたなは情報をあなたがそうすることになるコンテキストに加えるためにテンプレートに頼っている時が翻訳の後のそれ以後を調べるように注意しなければならない点にまた、注意してください。
テンプレートでの #set() ステートメントを経たコンテキストへの変更点は、
外のコンテキストだけに影響を及ぼすことになります。
それで、テンプレートからデータが内部のものの上へ置かれたのを期待して、
あなたが外のコンテキストを捨てないことを確認してください。
この機能は多くの使用を持ちます、 最も共通のものはこれまで提供している階層化されたデータ・アクセスと toolsets です。
前に言及されるので、このガイドの現在の範囲を越えて以外、Velocit yコンテキスト仕組みはまた、
拡張可能です。
あなたが興味を起こすならば、提供されたコンテキストがどのようにまとめられるかについて見るために、パッケージ org.apache.velocity.context でクラスを見てください。
しかし、メモリサポートとしてデータベースを使う[ goofy ]
ものを含む交互の実装を示す配布において、2、3の例が、examples/context_example
ディレクトリにあります。
に注目してください、これらの例は、サポートされていなくて、デモンストレーション/教育的な目的だけのためにそこにあることに注意してください。。
Objects Created in the TemplateJava コードがオブジェクトを扱わなければならないところがつくった2つの共通の状況が、 テンプレートで実行時にあります：
テンプレート作者が Java コードによってコンテキスト内に位置する オブジェクトのメソッドを呼び出すとき
テンプレートはオブジェクトをコンテキストに加えるとき、 Java コードはそれらのオブジェクトにアクセスすることができ、その後マージ処理が完了します。
これらの場合を扱うには、とても単純で2、3の事柄を知っていればよい:
java.util.ArrayList オブジェクトです。
したがって、テンプレートでつくられる配列を受け入れるようにできているあなたのメソッドは、これを考慮して書く必要があります。
#set()を通してコンテキストに置かれるintでsetFoo( int i )を呼ぶことはきれいに動作することになります。
VelocityContext（またはAbstractContextに由来するどんなコンテキストでも）によって提供される機能のうちの1つは、キャッシュしているノード特定のイントロスペクションです。 一般にあなた開発者あなたのコンテキストとして VelocityContext を使うとき、 これについて心配する必要がありません。 しかし、この機能のについて知っておいて欲しい既知の使い方のパターンがあります。
それがノードを訪問するので、VelocityContext はテンプレートで構文ノードに関するイントロスペクション情報を蓄積することになります。 そして、以下の状況では：
あなたの VelocityContext がメモリ「リーク」（それは、本当に集まっているより多くのイントロスペクション情報だけです。）をするように見えることになることはあり得ます 起こることはそれが訪問する各テンプレートのために、それがテンプレート・ノード introspection情 報を蓄積するということです、そして、キャッシュしているテンプレートが離れてそうであるので、それが各時新しいテンプレートを訪問していることは VelocityContext に現れます。 それゆえに、それはより多くの introspection 情報を集めて、成長します。 あなたが以下のうちの1つ以上をすることを特に推奨します。:
VelocityContext useThis = new VelocityContext( populatedVC ;
この作業外のコンテキストがそうすることになる、ストア introspection が、
データをキャッシュして、内部のコンテキスト（そのままに空にしてください。）から、
どんな要請されたデータでも得ます
慎重です−コンテキストとそれへのあなたのテンプレート立場データがそうな、それが以降の繰り返しにおいて使われることになることを予想します、あなたは他のうちの1つをする必要があることになりますどんなテンプレート#set()ステートメントでも最も外部のコンテキストに保存されることになるので、修理します。
詳細はContext chainingで議論を見てください。
Velocity の最も一般的な利用は、WWW のための Java Servlet プログラミングの領域です。 Velocity がこの作業のために最適な理由がたくさんあります。 そのうちの大きな理由のひとつは、Velocity のコード層からのプレゼンテーション層(またはVIEW)の 分離の励行です。 このことについては、 これに多くのリソースがふくまれています。
servlet 環境においてVelocityを使う基本テクニックは、非常に単純です。
ごく狭い場所で、あなたがしなければならない全ては、提供された VelocityServlet
ベース・クラスを 拡張して、ひとつのメソッド（handleRequest()）
を実装するだけです。
それは、本当にあなたの servlet 開発において Velocity
を使うことを要求される全てです。
Velocity 1.1 では、2つの handleRequest() メソッドが、あります：
public Template handleRequest( Context )
これは、2つのメソッドの古い方です。 このメソッドは、あなたが有効なテンプレート・オブジェクトを返すことを必要とします。 有効でなかったり、nullだったりすると、これはエラーと見なされて、 その結果としてerror()エラー ハンドリングメソッドが呼び出されます。 必要であれば、あなたはerror()をオーバーライドできます。nullを返すときに、なにか期待する動作をさせたい場合 (例えば、あなたは要求を向け直したいとか)の場合には、 次に説明するより新しいメソッドを使用することが推奨されます。
public Template handleRequest( HttpServletRequest, HttpServletResponse, Context )
これは2つのいつものように、最も確実で最新の注意事項のためには、 Javadoc API ドキュメンテーションを参照してください。handleRequest()メソッドのより新しいものです。 そして、バージョン 1.1 において実装されます。 このメソッドとの違いは、Contextと同じように、HttpServletRequestとHttpServletResponseオブジェクトがメソッドに対する引数としてあなたに渡されるということです。 他の違いはこのメソッドが全ての処理がメソッドによって取り扱われたことを明らかにするためにnullを返すことができるということです、そして、その Velocity は呼び出しrequestCleanup()以外は何もしません。 そして、あなたは、例えば、要求をリダイレクトしたいという場合には、 これはとても役に立ちます。
以下のコードは、例ディレクトリにおいて配布に含められる SampleServlet.java クラスと 同じ物です。
見覚えがありますか？ コンテキスト・オブジェクトを作成することを除いては、VelocityServlet ベースクラスによってあなたのために完了していますまた、VelocityServlet ベースクラスによってあなたのために merge() ステップを行います、これは我々がこのガイドの初めに言及した基本的なコード・パターンと同じです。 我々は、コンテキストを取り出し、我々のアプリケーション・データを加えて、テンプレートを返します。
handleRequest()メソッドに渡されるデフォルトのContextオブジェクトは、現在のHttpServletRequestとHttpServletResponseオブジェクトを含みます。
これらは、コンテキストで置かれて、定数 VelocityServlet.REQUEST（値=『req』） と
VelocityServlet.RESPONSE（値=『res』）を使います。
あなたの Java コードにおいてアクセスするためには、これらのオブジェクトを使用します：
そして、あなたのテンプレート:
より高度な使い方として、VelocityServlet ベース・クラスは、
要求処理を取り扱うことの一部をオーバーライドすることが可能です。
以下のメソッドは、オーバーライドすることができます：
Properties loadConfiguration( ServletConfig )
標準的な設定の仕組みをオーバーライドし、追加、変更や設定プロパティ設定をすることができます。 これは、実行時に webapp root に絶対パスをセットしたり、オーバーライドするか、 テンプレートとログ・パスを増やすことに役立ちます。
Context createContext(HttpServletRequest, HttpServletResponse )
あなた自身コンテキスト・オブジェクトを作成することができるようにします。 これは、例えば連鎖をしたり、ツールやデータで事前ロードしたりといった より高度な技術を許します。 デフォルトの実装では、単に要求された VelocityContext オブジェクトを返し、 応答オブジェクトは内部を置きます。 若干のservletコンテナ実装で occurr な要求と応答オブジェクトは、 それがそうするかもしれない introspection 問題を避けるために単純なラッパー・クラスで包まれてあります。 あなたは通常要求と repsponse オブジェクトを使用することができます。 そして、テンプレートからのどちらでものメソッドにアクセスします。 それがあなたにとって重要ならば、それら特に javax.servlet.XXXX でないという注意。
void setContentType( HttpServletRequest,HttpServletResponse )
要求を調べて、要求またはクライアントに依存した、 あなた自身の content-type を設定することができます。 プロパティにおいて指定されないならば、 デフォルトの実装は、velocity.properties に指定した値かそれが無ければ デフォルトで「text/thml」が設定されます。
void mergeTemplate( Template, Context, HttpServletResponse )
出力ストリームを生成するためにあなたを許します。 VelocityServlet は非常に効率的な Writer クラスのプールを使いますので、 これは、たいてい特別な状況においてオーバーライドされます。
void requestCleanup( HttpServletRequest,
HttpServletResponse , Context )
要求処理の終わりに、クリーンアップまたはリソース再利用でもどんなことでも するためにあなたを許します。 デフォルトは、何もしません。
protected void error( HttpServletRequest,
HttpServletResponse, Exception )
要求処理での例外発生時に呼ばれるエラー・ハンドラー。 デフォルトの実装は、ユーザーへスタックトレースと例外情報の 単純な HTML メッセージを送ることになります。 クライアント・メッセージとより高度な問題取り扱いを カスタマイズするためにオーバーライドします。詳細情報は、Javadoc API ドキュメント を見てください Deployment
あなたがあなたの Velocity ベースの servlets を配備するとき、 あなたは確かにあなたのプロパティ・ファイルが Velocity 実行時に 設定するために使われることを確実にしたいことでしょう。 Tomcatの下で、これを達成する1つの方法があなたの Webアプリ（webapps/appname） の root ディレクトリに、あなたの velocity.properties ファイルを置くこと、 それから、以下をあなたの Web-INF/web.xml ファイルに加えてください：
全てが正しいと仮定して、MyServlet がロードされるとき、その内部のデフォルトに依存するよりも、それ自体で初期化するために velocity.properties ファイルを使用する方が確実なります。
注意: Velocity がそれの中心のコア Runtime クラス用に singleton モデルを使うので、 それを CLASSPATH または servlet ランナーの最上位の lib ディレクトリに置くというゆうむしろ、 Webアプリケーションクラスローダーがあなたの実行時インスタンスを管理するのを確実にするために、Velocity を使用するすべての Web アプリケーションの Web-INF/lib ディレクトリに velocity-XX.jar を置くのは非常に良い考えです。
この配備方法は、異なる Web アプリケーションが Velocity 構成の衝突回避を確実にします。
Velocity は汎用的に使用できるツールとして設計されたので、 それは一般的なアプリケーション・プログラムでそれが servlets であるのと、 同じくらい役に立ちます。 一般に、あなたはこのガイドの初めに検討されたのと同じプログラミング・パターンを使うことができますが、我々が簡単に使用できるように VelocityServlet ベースクラスを提供したのと同様に、 アプリケーション使用に対して2、3のユーティリティ・メソッドが用意されているます。 あなたがアプリケーション・プログラマーとして持つ唯一の新しい責任は Velocity 実行時エンジンを初期化することです、しかし、それは簡単です。
The Velocity Helper Class
Velocity は、Velocity（org.apache.velocity.app.Velocity）と呼ばれているアプリケーション・ユーティリティ・クラスを含みます。
このクラスの目的は、Velocity（Velocityを使う際により簡単にする役に立つユーティリティ・ルーチンと同様に）を初期化することを要求される必要なメソッドを提供することです。
このクラスはプロジェクトの javadoc で文書化されますので、完全な詳細は、それを参照してください。
このドキュメンテーションは、本質的にはチュートリアルのつもりです;
したがって、API 情報と重複しますが、Javadoc は最終的な情報源となります。
Velocity 実行時エンジンはリソースを提供する singleton インスタンスです。 そして、全ての Velocity ユーザーに対するロギングと他のサービスは同じ JVM で実行します。 したがって、実行時エンジンは、一度だけ初期化されます。 あなたは一度ならず Velocity を初期化しようとすることができます、 しかし、最初の初期化だけが適用されます。その他の初期化の試みは、無視されます。 Velocity ユーティリティ・クラスは、現在実行時エンジンの構成で使用される 5つのメソッドを提供します。
5つの設定メソッドがあります
setProperty( String key, Object o )keyに値oを設定します。
値は、一般的に String です、しかし、値のコンマで区切られたリストが、
特別な場合においてまた、あることがありえます（ひとつの String 内で例えば、
"foo, bar, woogie"）起こることになる他のものと同じくらいよい。
Object getProperty( String key )init()init( Properties p )java.util.Propertiesオブジェクトに含まれるプロパティで、
実行時に初期化します。init( String filename )注意: それぞれの場合、デフォルトプロパティは、基底の設定として使用され、 独自の値が、デフォルトのプロパティに上書きされます。 つまり、オーバーライドされないどんなデフォルトのプロパティでも、 実質的に残ることになります。 これは、完全なセットよりむしろあなたが変更したい部分のプロパティだけ 指定できるという利点があります。
その他の注意点は、 init() 呼び出しは、
アプリケーションに悪影響を与えずに一度以上実行される可能性があることです。
しかし、init() 機能のいずれかへの最初の呼び出しは、
そこでセットされる構成プロパティで、エンジンを構成することになり、
そして、どんな更なる構成変更点でもまたは init()
呼び出しは無視されます。
Velocity を初期化するのに最も共通の方法は、このようになります：
java.util.Propertiesにおいて、それから init( filename ) または init( Properties ) を呼び出します。
setProperty() を個々に使って設定値をセットしてください、それから、
init() を呼んでください。
このメソッドが、一般にすでに彼ら自身の構成管理システムを持つようなより高度なアプリケーションによって使われます
−
これは、例えばそれが実行時に生成する値に基づく Velocity を設定するようなアプリケーションを許します。
一旦、実行時に初期化されるならば、あなたはそれであなたが願うものをすることができます。 これは大部分は出力ストリームにテンプレートをレンダリングする周囲を循環します。 そして、Velocity ユーティリティ・クラスは簡単にこれをするためにあなたを許します。 現在、メソッドとそれらがするものの簡潔な説明は、ここにあります：
evaluate( Context context, Writer out, String logTag,
String instring )evaluate( Context context, Writer writer, String logTag,
InputStream instream )invokeVelocimacro( String vmName, String namespace, String params[],
Context context, Writer writer )evaluate() メソッドによって完成していることがありえます。
ここでは、あなたは単にあなたが呼ばれることを望むvmに名をつけ、
VMに渡す引数の配列、データの Context、出力のための Writer を作成します。
注意: VM 引数はコンテキスト（arg.として使われる文字通りのデータよりむしろ）でのデータ・オブジェクトの『キー』でなければなりません。
これは、多分変わることになるでしょう。
mergeTemplate( String templateName, Context context, Writer writer )
boolean templateExists( String name ) name が現在設定されたリソース・ローダーで見つけることができるかどうか判断します。
一旦我々がこれらの基本のヘルパーを知るならば、Velocity を使う Java プログラムを書くことは簡単です。 ここでは、：
我々は、このプログラムを実行して、我々のプログラム（我々がデフォルトの構成プロパティを使ったので、テンプレートをロードする場所は現在のディレクトリです）と同じディレクトリにおいて、テンプレート testtemplate.vm を持ちます、我々の出力は、こうなるはずです：
そこで我々が使ったテンプレート（testtemplate.vm）は 以下のようになります。
これでここにあるもの全てです!
我々のプログラムでmergeTemplate()とevaluate()
を使う必要はなかったことに注意。
それには、デモンストレーション目的のために両方とも含まれます。
あなたは多分メソッドのうちの1つだけを使うことになるでしょう、
アプリケーション必要条件以外は、あなたがやりたいようにして構いません。
これはこのガイドの初めに言及された『基本的パターン』と少し異なるように見えます、
しかし、それは本当に同じものです。
最初に、あなたはコンテキストを作って、それを必要とされるデータで満たしています。
そこで、この例で異なっているのは、mergeTemplate() を使用して
いる部分す。mergeTemplate() は、Runtime クラスの低レベルの呼び出しを
利用して、あなたのためにテンプレートの取得とマージを行なっています。
第二の例では、あなたが String 経由で動的にあなたのテンプレートを作っていること、
そのため、処理の部分で『テンプレートを選びます』のためのanalgousで、
evaluate() メソッドの一部は、あなたのために
低レベルの呼び出しを使ってマージを行ないます。
それで、上記の例はVelocityテンプレートエンジンを使用するパターンを単純な ままにしていますが、ユーティリティ機能が繰り返しのコツコツした作業や、その他のテンプレートファイルの内容をテンプレートにするオプションなど行なっています。
Exceptions
Velocity が、解析/マージのサイクルで投げることになる3つの例外があります。
また、I/O の問題、その他からやって来ることになる例外がこれに追加されます。
それらは、パッケージ org.apache.velocity.exception で見つけられます：
ResourceNotFoundExceptionParseErrorExceptionMethodInvocationExceptionそれぞれの場合、メッセージは実行時ログに入れられます。 詳細は、Javadoc API ドキュメンテーションを見てください。
Miscellaneous Details
The latter method is convenient, because you can either fill it directly
from a separate properties file via the load() method, or even
better, you can fill it dynamically from your own application / framework's
property set at runtime. This gives you the freedom to combine all of the
properties for your app into one properties file.
上記の例がデフォルトのプロパティを使ったが、あなた自身のプロパティをセットすることは非常に単純です。
あなたがしなければならない全ては、どこかにプロパティ・ファイルを作って、そして、Velocity ユーティリティ・クラスの init(String) メソッドへそのファイルの名前を渡す、または java.util.Properties オブジェクトを作って、要求されたプロパティと値を加えて、そして、init(Properties) メソッドへそれを渡します。
後者のメソッドは便利です、あなたがそうすることができる、両方の一杯直接 load() メソッドによる別々のプロパティ・ファイルからそれ、あるいは、よりよく、あなたは実行時でセットされるあなた自身のアプリケーション/フレームワークのプロパティから動的にそれを満たすことができます。
これは、あなたに1つのプロパティ・ファイルにあなたのアプリのためにプロパティの全てを結合する自由を与えます。
我々がテンプレートフォームをロードするのにカレントディレクトリではなく、 異なるディレクトリを使いたい場合には、このようにします：
そして、ディレクトリ /opt/templates があり、そこにテンプレート testtemplate.vm があると仮定すると、これはうまく動きます。
あなたがこれを試して、問題を持つならば、必ず情報については velocity.log を見るようにしてください−エラー・メッセージは何が間違っているかについて理解するためにかなり役立ちます。
バージョン 1.1 から、Velocity にきめの細かいイベントハンドリングシステムが追加されました。
EventCartridge は、あなたのイベントハンドラーを登録たり、必要であればマージするときに
イベントハンドラにアクセスすることができるクラスです。
現在、3つのイベントを扱うことができ、それらは org.apache.velocity.app.event
パッケージで見つけられます。
org.apache.velocity.app.event.NullSetEventHandler
#set() の結果 null が割り当てられたとき、これは通常ログに記録されます。NullSetEventHandlerは、この状態のロギングを'禁止'するとができます。
public interface NullSetEventHandler extends EventHandler { public boolean shouldLogOnNullSet( String lhs, String rhs ); }
org.apache.velocity.app.event.ReferenceInsertionEventHandler
ReferenceInsertionEventHandlerは、出力時のストリームと 修正のためにリファレンス($foo)値の 書き出し時にぞぞれ割り込みを開発者に許可します。public interface ReferenceInsertionEventHandler extends EventHandler { public Object referenceInsert( String reference, Object value ); }
org.apache.velocity.app.event.MethodExceptionEventHandler
ユーザから提供される例外が投げられるとき、MethodExceptionEventHandlerは、Class、メソッド名、投げられた 例外とともに実行されます。ハンドラーは、メソッド呼び出しの値を戻すのに 使われる有効なオブジェクトを戻すか、ユーザに通知するためのラップした あらたな例外MethodInvocationExceptionを投げます。public interface MethodExceptionEventHandler extends EventHandler { public Object methodException( Class claz, String method, Exception e ) throws Exception; }
Using the EventCartridge
EventCartridge の使用方法はとても簡単です。
以下の省略された例は、org.apache.velocity.test.misc.Test
を参照しています。
Velocity の実行時構成は、下でリストされる構成キーの集合によって制御されます。 通常、これらのキーは、値を持ち、それらは、String、コンマで区切られた String のリスト、 CSV と呼ばれるコンマで区切られた値です。
デフォルト値の設定は、Velocity の jar に含まれており、 /src/Java/org/apache/velocity/runtime/defaults/velocity.defaults にあり、 これは Velocity を使うための設定の元になります。 これは Velocity が常にそれのために「正しい」値を持つことになることは起動時に構成キーであることを確実にします、しかし、それはあなたが欲しいものでないかもしれません。
init() 実行以前に指定されるどんな値でも、デフォルトの値を置換します。 したがって、あたなが変更したいキーの値のみを変更すればよく、残りは 気にする必要はありません。さらに、我々はさらに多くの機能と設定を追加 をいきますが、あなたは自分の設定ファイルを変更する必要はありません。 Velocity エンジンは、常にデフォルト値を持ちます。
設定 API についての詳細は上のセクション Using Velocity In General Applications を参照してください。
Velocity の挙動を制御する構成キーは、下でリストされます。 カテゴリーによって組織化します、各キーはそれでリストされてす。 そして、現在のデフォルトは「=」記号の右辺の値です。
Runtime Log
runtime.log = velocity.log
エラー、警告と情報を提供するメッセージのためのログ・ファイルのフルパスと名前。
絶対パスでければ、位置は「現在のディレクトリ」の相対パスとなります。
runtime.log.logsystem
このプロパティには、デフォルトの値がありません。
Velocity にインタフェース org.apache.velocity.runtime.log.LogSystem. で
サポートするロギングのクラスのインスタンス・インスタンスを与えるのに使われます。
そして、それはあなたの他のアプリケーション付きのメッセージがロギングするログが送る
Velocity の組合せを許します。
詳細は、
Configuring the Log System
セクションを見てください。
runtime.log.logsystem.class =
org.apache.velocity.runtime.log.AvalonLogSystem
Velocity-instantiated ログシステムのために使用されるクラスです。
runtime.log.error.stacktrace = false
runtime.log.warn.stacktrace = false
runtime.log.info.stacktrace = false
trueにすると、これらのエラーカテゴリーのスタックトレースを有効にします。
これは大量のログを生成します。
runtime.log.invalid.references = true
falseにすると、リファレンスが無効のときのログ出力がされません。
出荷時には false にすると良いでしょう。
デバッグ時には、とても役立ちます。
runtime.log.logsystem.avalon.logger = name
ユーザに Avalon 構成で LogSystem インタフェースを使ったラップ無しで既存のログ
name の指定を許します。
注意: あなたは、またデフォルトのログシステムとしての
runtime.log.logsystem.class =
org.apache.velocity.runtime.log.AvalonLogSystem を変更しなければ
なりません。これは、Avalon ログシステムがデフォルトログシステムで残ることを
保証していません。
Character Encoding
input.encoding = ISO-8859-1
(テンプレート)入力のエンコーディング文字を指定します。
これを使用すると、テンプレートで UTF-8 のような別のエンコーディングを
使用することができます。
output.encoding = ISO-8859-1
VelocityServlet と Anakia からの出力ストリームのための文字エンコーディング
#foreach() Directive
directive.foreach.counter.name = velocityCount
#foreach() 指令で使用され、ループカウントのためのコンテキストキー
として使用されるもじれつを定義する。テンプレートは、ループカウントとして
$velocityCount でアクセスできる。
directive.foreach.initial.value = 1
#foreach()ループで参照されるループカウンタのための開始時のデフォルト値
#include() and #parse() Directive
directive.include.output.errormsg.start
=
directive.include.output.errormsg.end
= ]]>
#include() 指示に関する問題の場合、入力ストリームのエラー・メッセージ用に
開始タグと終了タグを定義します。.start タグと .end タグが定義されるならば、
エラー・メッセージは、.start と .end がプロパティ値を呼ぶ形式で
「.start msg .end」の、ストリームへの出力になります。
.start タグ と .end（次の）タグが定義されるならば、
レンダリング・ストリームへの出力は起こるだけです。
directive.parse.maxdepth = 10
テンプレートが解析できる深さを定義します。
テンプレートは、#parse() の中で、さらに #parse() 指示を含んでいるかもしれません。
この値は、#parse() 再帰の無限ループを防ぎます。
Resource Management
resource.manager.logwhenfound = true
リソース管理からの「見つかった」メッセージのロギングを制御を切り替える。
リソースが最初に見つかったときに、リソース名とローダーのクラス名が
実行時ログに通知されます。
resource.loader = <name> (default = File)
複数値のキー。値のCSV形式を受け入れる。
リソースローダーの Public 名が使用される。この public 名は、
リソースローダーの特定のプロパティを指定するのに使用される。
注意: 複数値のキーでは、"file, class" (クオート無しで)とような値を渡すことが可能になり、
以下に示されるように2つ値がローダーによって設定値となる。
<name>.loader.description
= Velocity File Resource Loader
与えられたローダーの説明文字列。
<name>.resource.loader.class
= org.apache.velocity.runtime.resource.loader.FileResourceLoader
ローダーのクラスの実装名。デフォルトローダーは、ファイルローダー。
<name>.resource.loader.path = .
複数値のキー。CSV形式の値を受けれます。
Rootは、ローダーが読み込むテンプレートからです。テンプレートは
このルートのサブディレクトリに存在しないければなりません。
例えば、 homesite/index.vm 。 この設定キーは、現在のところ
FileResourceLoader と JarResourceLoader に適用されます。
<name>.resource.loader.cache = false
ローダーでのテンプレートのキャッシュ制御。
配備と開発の問題を簡単にするために、デフォルトは false です。
製品配備のときには、true にすべきです。
「true」のとき、modificationCheckInterval プロパティが適用されます。
これは、リロード制御の便宜のためのキャッシュ機能の制御を許可します。
テンプレートが頻繁に更新され、
アプリケーションに戻ったり、サーブレットエンジンにその機能を
望んでいない場合や許可されていない場合などに
ホスティング環境や ISP 環境で役に立ちます。
<name>.resource.loader.modificationCheckInterval = 2
これは、キャッシュがオンにされたときに、修正がされたかチェックする間隔を
秒数で指定します。この数字が > 0 の場合、テンプレートが修正されたか
チェックする間隔を秒であらわしています。もしテンプレートが最後にチェック
したときから変更されていれば、それは再ロードされて、再解析されます。
そうでなければ、何もしません。
また、この数字が <= 0 のとき、修正チェックは行なわれません、プロパティ
cache(上) が true と仮定するとテンプレートを最初にしようする
ときに一度だけ、読み込まれ解析され、それはアプリケーションやサーブレットエンジンが
リスタートされるまでチェックやリロードはされません。
実例を示すために、ここで、例が、FileResourceLoader をセットアップすることはどのように管理されるかについて示して、デフォルトの Velocity プロパティからのとられます
Velocimacro
velocimacro.library = VM_global_library.vm
複数値のキー。CSV 形式の値を受け入れます。
Velociry 実行時エンジンが開始したときに、ロードされる
Velocimacro ライブラリのファイル名です。これらの Velocimacro は、
すべてのテンプレートでアクセスすることができます。ファイルは
ファイルローダーリソースパスのルートからの相対パスを仮定しています。
velocimacro.permissions.allow.inline = true
テンブレート内で #macro() 指示を通して新しい Velocimacros の定義を可能にするかどうかを
決定します。デフォルト値は true です。そして、どんなテンプレートでも新しいVelocimacrosを定義して、使うことができることを意味します。
注意: 他のプロパティに従い、それらの #macro() ステートメントがグローバルな定義を置き換えることができるます。
velocimacro.permissions.allow.inline.to.replace.global = false
テンプレート内で「inline」定義された Velocimacro が、起動時にロードされたライブラリ内の
Velocimacro定義を置換するかどうか制御します。
velocimacro.permissions.allow.inline.local.scope = false
Velocimacros の「プライベート」テンプレートのネームスペースの制御です。
true のとき、テンプレートで #macro() 指示で作成した Velocmacro は、
テンプレートを定義したところからのみアクセスすることができます。
これは、それらが起動時にロードされるグローバルやローカルのライブラリ
にない限り、Velocimacros が共有できないことを意味します。（上記参照。）
また、テンプレートがお互いに干渉することが無いことを意味します。
「デフォルト」の Velocimacro 定義がグローバルであるかそのローカルのライブラリにある所で、
このプロパティもテクニックを許します、そして、テンプレートはそのテンプレートの範囲内で使用のために実装を「オーバーライド」できます。
これは、このプロパティが true の場合に、テンプレートのネームスペースは、
Velocimacro の検索は、グローバルネームスペースより先に行なわれるので、
オーバーライドが働きます。
velocimacro.context.localscope = false
Velocimacro の範囲内のリファレンス・アクセス（set/get）がコンテキストを変えることになるか、その Velocimacro でローカル範囲であることになるかどうか制御します。
velocimacro.library.autoreload = false
Velocimacro ライブラリの自動ロードを制御します。
trueにセットすると、Velocimacro ライブラリソースを
Velocimacro が変更されたか確認するようになり、必要であればリロードされます。
これは、ちょうど通常のテンプレートと同じように、
サーブレットコンテナやあなたのアプリケーションをリスタートせずに
Velocimacro ライブラリの変更をすることができるようになります。
これは、リソースローダーのキャッシュが off (つまり
file.resource.loader.cache = false ) の場合のみ動作します。
この機能は、開発の用途を目的としており、製品のためではありません。
String Interpolation
runtime.interpolate.string.literals = true
VTL String リテラルの展開の仕組みを制御します。
VTL String リテラルは、特に一般に#set() ステートメント、リファレンスのメソッド呼び出し、
VM へのパラメータにおいてまたは指示的な VTL への引数として使われる二重の引用符を使っているストリングであるという注意。
詳細はVTLリファレンスを見てください。
Runtime Configuration
parser.pool.size = 20
このプロパティは、Velocity が起動時に作成して、プールに保持する
パーサの数を設定します。
デフォルトでは、20 のパーサーですが、たいていの使用のでは十分なはずです。
Velocity がパーサーを使い果たすと、ログに記録され、必要に応じてそれらが
作成されます。
ただし、それらはプールに加えられないことに注意してください。
これは、標準的なパーサーのプールと比較して遅い操作ですが、
これは例外的な状態です。あなたがログ・メッセージに出ている場合には、
このプロパティの数字を増やしてください。
Velocity には、シンプルで柔軟性を兼ね備えてた素晴らしい2,3のロギング機能があります。
どんな特別な設定をしなくても、Velocity は、ファイルベースのログに
すべてのログメッセージを Velocity がインストールされた「カレントディレクトリ」
にに velocity.log という名前のファイルで出力します。
より高度な使い方をするユーザーのために、あなたは、
あなたの現在のロギングの機能に対して Velocity の全てのログメッセージを
統合させるかもしれません。
あなたのオプション
org.apache.velocity.runtime.log.LogSystem を実装しなければならなくて、それから単に構成プロパティ runtime.log.logsystem.class にクラス名を設定し、そして、Velocity は init 時にそのクラスのインスタンスを作ります。
あなたが他のプロパティも指定するために、あなたは別のクラス名を指定するかもしれません。
詳細については、
Velocity helper class と
configuration keys and values. を参照してください。
org.apache.velocity.runtime.log.LogSystem インタフェースを実装することによって、あなたは Velocity のロギング機能をあなたのアプリケーション現存のロギング・システムと統合することができます。
それから、あなたが init() を呼ぶ前に runtime.log.logsystem 構成キーによって、Velocity にクラスをロギング・インスタンスを渡してください、そして、Velocity はあなたのアプリケーション logger にメッセージをロギングすることになります。
詳細は、
Velocity ヘルパークラスと
キーと値の設定を参照してください。
とっても単純ならば、カスタム logger を作ります。 下のコードは、あなたがあなた自身のアプリケーションにおいてこれをするかもしれない方法の単純なスケッチです。
Simple Example of a Custom Loggerこれは、あなたの独自のアプリケーションで Velocity のロギングシステムを統合する 方法の簡単な例です。
Velocity についての基本的で重要な部分のうちの1つは、 リソース管理システムとリソース・ローダーです。 リソース管理システムがまた、非テンプレートリソース（特に #include() 指示を通してロードされるもの）を取り扱うことになるので、それらは「テンプレート」よりむしろ「リソース」とここで呼ばれます。
非常に柔軟なリソース・ローダー・システムは非常に柔軟なので、同時に、 一つ以上のリソース・ローダーを指定することができます。 これは設定とリソース管理において相当な柔軟性を許します、そしてさらに、 あなたの特別な要求のためにあなた自身のリソース・ローダーを書ことができます。
現在、下記で説明される4種類のリソースローダーがVelocityに含まれます。
注意: サンプル設定プロパティでは、ローダーの共通名が示されます(
例えば、'file'は、file.resource.loader.pathの「file」)。
この「共通名」は、あなたの設定では働かないかもしれません。
このシステムがどのように機能するかについて理解するために、
リソース設定プロパティに関するセクションを参照してください。
また、これらのローダーの各々は、パッケージ org.apache.velocity.runtime.resource.loader にあります。
file.resource.loader.path = <path to root of templates>
file.resource.loader.cache = true/false
file.resource.loader.modificationCheckInterval = <seconds between checks>
jar.resource.loader.path を除いて、プロパティは同一です、そこで、あなたはあなたがそこからリソースをロードしたい jar(s) のフルパスを提供します。
loader.path 用に jar を指定するために、あなたは java.net.JarURLConnection の標準の jar UR L構文を使います。
build/lib ディレクトリへの j2ee.jar を移動して、それからビルドするために、
jar-j2ee というビルドターゲットを使用して新しい velocity jar を構築します。
このローダーの詳細については、クラスorg.apache.velocity.runtime.resource.loader.DataSourceResourceLoaderについては javadoc を見てください。
Velocity のためにリソース・ローダーを設定することは簡単です。 制御のプロパティで、詳細は リソース設定 セクションでリストされています。
一つ以上のリソース・ローダーを設定することにおける最初のステップは、
Velocity への名前によるそれらを「宣言します」。
プロパティ resource.loader を使ってください、そして、一つ以上のローダー名をリストしてください。
あなたはあなたが欲しい何でも使うことができます−これらの名前が構成与えられたローダーと関連するために使われます。
そのエントリは、我々が「file」として知られているリソース・ローダーを 持つことになると宣言します。 次にすることは、重要なプロパティをセットすることです。 一番大事なのは、ローダーとして使用するクラスを宣言することです：
この場合、我々は Velocity に対して、「file」というリソースローダーを
設定し、それが
org.apache.velocity.runtime.resource.loader.FileResourceLoader
クラスを使用することを設定します。
次に、このローダーにとって重要なプロパティを設定します。
ここでは、我々は2、3のものを設定しました。
最初に、テンプレートを見つけるためのパスとして /opt/templates
を設定しました。
第二に、我々はキャッシュすることをオンにしました、そのため、
テンプレートまたは静的ファイルが読まれたあと、それはメモリにキャッシュされます。
そして、最後に、我々は新しいテンプレートのために更新チェック間隔を2秒にセットしました。
それらは、基本です。 以下は、異なる設定の2、3の例です。
何もしないデフォルト設定 : 名前のとおり、デフォルト設定をするので何も行なう必要はありません。 この設定はデフォルトのリソース・パスとして現在のディレクトリで FileResourceLoader を使います、そして、キャッシュは offです。 プロパティ・セットとして、次のように表されます：
複数テンプレートパス設定 : テンプレートの検索パスを「ノード」として複数のディレクトリを検索するように FileResourceLoader を使用するように設定します。 また、キャッシュを使い、テンプレートを10秒間隔で変更点があるかチェックします。 プロパティ・セットとして、次のように表されるます：
複数ローダー設定 : この設定は、同時に3つのローダー、FileResourceLoader、ClasspathResourceLoader と JarResourceLoaderをセットアップします。 ローダーは、最初に FileResourceLoader が参照され、それから ClasspathResourceLoader と最終的に JarResourceLoader と設定されます。 即座にテンプレートを置換するためにファイル・テンプレート領域に落とすことで 通常 jar 経由のものがクラスパス上でテンプレートが見つかるので jarを作り直さなくてもよくなります。
3つの名前「file」、「class」、「jar」があなたの都合と分類のためだけの単なるノードです。 それらはあなたが欲しい何ででもありえます−彼らが一緒にプロパティの集合を関連するために使われるだけです。 しかし、あなたが機能のいくらかのヒントを与える名前を使用することを推奨します。
注意: 3つとも全て適当な操作のために、ごくわずかな構成情報しか必要としないが、 ClasspathResourceLoaderが最も単純なものである。
バージョン1.1現在、テンプレートベースによるテンプレートリソースの文字エンコーディングの 指定をすることが可能です。 通常のリソースAPIは、エンコーディングを引数として渡すことが可能です：
org.apache.velocity.servlet.VelocityServlet :
public Template getTemplate( String template, String encoding )
org.apache.velocity.app.Velocity :
public static Template getTemplate(String name, String encoding)
public static boolean mergeTemplate( String templateName, String encoding, Context context, Writer writer )
encoding引数のための値は、 あなたの JVM でサポートされる通常のエンコーディング仕様です。(例えば「UTF-8」または「ISO-8859-1」)。 文字セットの公式名称は、ここを参照してください。
注意: これはテンプレートのエンコーディングだけに該当します。−出力エンコーディングはアプリケーション特有の問題です。
Velocity は柔軟性で単純なテンプレート言語で、XML データで動作するための理想的な環境です。 Anakia は、Velocity が XML から出力をレンダリングするためにXSLを置き換えるために使われる方法の例です。 このドキュメンテーションを含む Velocity サイトは、Anakia を使っている XML ソースから生成しています。 Jakarta サイトもまた Anakia を使用してレンダリングされています。 です。
通常、Velocity で XML を扱うことのパターンは、JDOM のような便利な Java でデータ構造にアクセスできるものを使ってあなたの XML を処理します。 それから、あなたは JDOM ツリーから直接 XML ドキュメントにデータのアクセスを行い、テンプレートを生成します。例えば、次の XML 文書から始めると：
ここで、次のようにコードを取り込む小さな Java プログラムを作成します。
（このやる方についての詳細は、配布のexamplesディレクトリにある
Anakia サンプルを参照してください。）
さて、通常の Velocity テンプレートを作ります：
そして、通常行なうように、 Context に JDOM ツリーを含ませることを使用してテンプレートをレンダリングします。 もちろん、これはもっとも単純な例というわけではありませんが、 しかし、あなたが Velocity テンプレートから直接簡単に XM Lデータにアクセスすることができることは基本を示しています。
Velocity で XML データを一定の型に合わせる1つの本当の利点は、
あなたが他のどのオブジェクトへのアクセスまたはアプリケーションが提供するデータを持つということです。
あなたは、XML 文書においてデータ・プレゼントを使うだけであることに限られていません。
あなたは、あなたが追加の情報をあなたの出力のために用意するか、ヘルプへのツールがより簡単な XML データで働くことを作ると定めるためにコンテキストに欲しい何でも加えるかもしれません。
Bob McWhirter の Werken Xpath
はそのような役に立つツールです−それが Anakia で使われる方法の例は
org.apache.velocity.anakia.XPathTool で見つけることができます。
XML と Velocity で起こる1つの問題は、XML エンティティによる処置への方法です。 あなたが出力ストリームにエンティティをレンダリングする必要があるとき、 1つのテクニックはVelocimacrosの使用を結合することです：
ここで escapeEntities() は、あなたのためにカプセル化を行なうメソッドです。 別のトリックは、コンストラクタ・パラメータとしてのコンテキストをとって、メソッドを実装するだけであるコード化しているユーティリティを作成することになっています：
"xenc" としてコンテキストを置く。そして次のように使用する:
これが、それがコンテキストで $xenc オブジェクトの get("sometext") を呼ぶために試みることになるように Velocity の introspection プロセスの利点があります。 そして xenc オブジェクトは、Context から値を取得することができ、エンコードして、戻します。
代わりに、Velocity がカスタム・コンテキスト・オブジェクトを実装することを簡単にして以後、 あなたは常に何にでも返されるストリングをコード化することを適用するあなた自身のコンテキストを実装することができました。 彼らがオブジェクトまたはストリング（それは、コード化することを必要とするかもしれません）を返すことができたので、メソッドの出力を提出することを避けることは直接呼ぶように注意してください。 指示的な #set() と使用によるコンテキストに、最初にそれらを置きます、例えば：
XML エンティティを扱うための前の提案は、Christoph Reck（Velocityコミュニティの活発な参加者）から行なわれました。 我々は、この文書に対する彼の[知らない]貢献に、非常に感謝して、彼の考えがあまりひどくたたきつぶされなかったことを望みます：）
我々は、この簡潔なガイドがあなたの Java プロジェクトで Velocity を使うのに役に立つ 紹介であることを望みます。また、Velocity に興味をもっていただいたことを感謝します。 我々は、このドキュメンテーションについてや、Velocity テンプレート・エンジンそのものに ついてのコメントは何でも歓迎します。
我々のメーリングリスト に参加して、徹底的に全ての詳細で、考え深くて建設的なフィードバックをお願いします。