1. はじめに
2. リソース
3. Velocity の動作原理
   • 基本パターン
4. コンテキスト
   • 基本
   • インタラクティブにオブジェクトをサポートする #foreach()
   • コンテキスト・チェイン
   • テンプレートで作成されたオブジェクト
   • その他のコンテキスト問題
5. ServletでVelocityを使う
   • サーブレット・プログラミング
   • 展開
6. 一般的なアプリケーションでVelocityを使う
   • Velocityヘルパークラス
   • 例外
   • いろいろな詳細
7. EventCartridge とイベントハンドラー
8. Velocity設定キーと値
9. ログシステム設定
   • カスタムログの簡単な例
10. リソース読み込み設定 (テンプレートローダー)
    • 設定例
11. 国際化のためのテンプレートエンコーディング
12. Velocity と XML
13. まとめ

Velocityは、Javaに基づくテンプレート・エンジンであり、あなたのデータをフォーマットしたり表示したりするために、文書をレンダリングしたり容易に作成するための単純で強力な開発ツールです。 このガイドでは、Velocityを使用した開発の基本概要について説明していきます。 そして、Velocity使い方のために2つの主な使い方に焦点を当てます：

• サーブレットベースの WWW 開発
• 一般的なアプリケーションでの使用

Velocityを使ってあなたのサーブレットでクラスに基づいたVelocityServiceクラスを 使って非常に簡単にサーブレットを開発すること、役に立つユーティリティクラスを 使用してアプリケーション開発をすることに関して、あなたは、これらの間に本質的な 違いはないということが分かると思います。

はじめに

この情報がVelocityサイトの上の、そして、ドキュメンテーションの中の見つけられたどこか他の所であるが、それはcompletenessのためにここで含まれます。 Velocityをあなたのコンピュータで実行するのは、非常に簡単です。 全てのディレクトリ参照はVelocity配布ツリーのrootに関連してることに 注意してください。

1. Velocity配布を入手してください。 リリース版や、夜間リポジトリスナップショットや、直接CVSコードリポジトリなどを 利用することができます。 うまく動作するとは思いますが、しかし、最新の機能のためには、夜間スナップショットが、おそらく最良の方法でしょう。 詳細情報は、ここを参照してください。
2. Java 構築ツールの Jakarta Antを まだインストールしていない場合には、まずそれをインストールしてください。 Velocityを構築するのに必要ですし、Velocityを使うのにも必要です。
3. 配布のbuild ディレクトリに移動します。
4. ant <build target>とタイプします。ここで<build target>は以下のうちの一つです。
   • jar binディレクトリにVelocityの完全版を 構築します。jarは、'velocity-X.jar'と呼ばれます。ここで'X'は、現在のバージョン番号です。 あなたに特定の記憶場所考慮がない限り、それがあなたが必要とするすべてを含むので、 都合のためにこのjarを使ってください。
   • jar-core binディレクトリにサイズの小さな'velocity-core-X.jar'という名前の Velocity jarを構築します。このjarには、Velocity機能のコアが含まれていますが、 例、Anakika、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ディレクトリに1部のj2ee.jarを置かなければなりません（またはリンク）。 我々は、配布の一部としてそれを提供しません。 よいソースはhttp://java.sun.com/にあります。
   • 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 それに対するテストVelocityは、そうすることになります（jarの後）テストのtestbedされたセットが、ルーチンです
   • help 利用できる構築ターゲットの一覧を表示します。
5. テストはビルドでは必要ではありませんが、よい考えです。 上で示されるtestターゲットを使ってください。
6. これでおしまいです！ Velocityは、使用する準備ができました。 あなたのクラスパスまたは他の適切な場所にjarを置きます（もしサーブレットで使うようなwebappのlibディレクトリなど）
7. あなたが例（それは着くことは始まった時を非常に推薦されます）で、作用に使用を望むならば、ant examplesを通して例を構築してください。

ちょっとした2、3のリソースと利用できる例がプログラマーに対して用意してあります、 そして、我々はあなたが我々の例と、ドキュメントとソース・コードを見ることをお勧めします。 素晴らしいソースの一部は、以下の通りです

• ユーザと開発者のコミュニティ : メーリングリスト から参加してください。
• メーリングリスト･アーカイブ : http://www.mail-archive.com は、そのひとつです。 'velocity' と検索語に入れて -user, -dev アーカイブを見てください。
• ソースコード : src/java/... : Velocityプロジェクトのすべてのソースコードがあります。
• アプリケーション例 1 : examples/app_example1 : アプリケーションプログラムで、Velocityをどのように使うか示した簡単な例
• アプリケーション例 2 : examples/app_example2 : Velocityアプリケーション・ユーティリティクラスを使用したアプリケーションプログラムの簡単な例
• servlet 例 : examples/servlet_example1 : サーブレットでVelocityを使用する方法を示した簡単な例
• logger 例 : examples/logger_example : 全てのログメッセージを受信するためにVelocityを使ってカスタムログを作成して登録する 簡単な例
• XML 例 : examples/xmlapp_example : Velocityテンプレートを使用してXMLドキュメントデータへのアクセスと読み込むために JDOMをの使い方の簡単な例。ドキュメントツリーを渡り歩くためのVelocimacroの 再帰のデモも含まれます。
• イベント例 : examples/event_example : Velocity 1.1のAPIでイベントハンドリングを使った例
• Anakia アプリケーション : examples/anakia : XMLデータのレンダリングのスタイルシートを生成するためにVelocityを使った アプリケーションの例
• フォーム Webアプリ : examples/forumdemo : サーブレットベースのフォームアプリケーションの動作例
• ドキュメント : docs : htmlでVelocityプロジェクトのために 生成されたすべてのドキュメント
• API ドキュメント : docs/api : Velocityプロジェクトのために生成されたJavadocドキュメント
• テンプレート : test/templates : テストベッドディレクトリ内のテンプレートの大きな集合で、 VTL(Velocity Template Language)の使い方のすばらしいソースがあります。
• context 例 : examples/context_example : Velocity contntを拡張することのできる2つの例をがあります。 上級者向け。

上の全てのディレクトリの参照は、配布rootディレクトリと関連しています。

'The Fundamental Pattern'

アプリケーションプログラムやサーブレットでVelocityを使う場合 (または正確にはその他の場合も)、以下のことを行なう必要があります。

1. Velocityの初期化。 (一度だけ行います)
2. Contextオブジェクトの生成(more on what that is later).
3. Contextへあなたのデータオブジェクトの追加
4. テンプレートの選択
5. 出力を生成するためにあなたのデータとテンプレートの'マージ'

コードでは、このようになります。

	import java.io.StringWriter; import org.apache.velocity.VelocityContext; import org.apache.velocity.Template; import org.apache.velocity.app.Velocity; Velocity.init(); VelocityContext context = new VelocityContext(); context.put( "name", new String("Velocity") ); Template template = null; try { template = Velocity.getTemplate("mytemplate.vm"); } catch( ResourceNotFoundException rnfe ) { // couldn't find the template } catch( ParseErrorException pee ) { // syntax error : problem parsing the template } catch( Exception e ) {} StringWriter sw = new StringWriter(); template.merge( context, sw );

これが、基本的なパターンです。 とっても単純ですね？ これは、通常あなたがテンプレートをレンダリングするのにVelocityを使うときに行なうことです。 あなたは多分必ずしもこのようにコードを書くことにはならならないでしょう−我々はservletとアプリケーション・プログラマーの双方に対して、より簡単にするための2〜3のツールを用意しています。 このガイドの中で後ほど、我々は両方のservletsで一般的なアプリケーションと同様にVelocityを使うことについて説明します、そして、我々は我々がより簡単にするために提供するツールを検討します。 どちらの場合も上記のシーケンスがその舞台裏で動いているのは事実です。

The Basics

『コンテキスト』の概念は、Velocityにとって主要で、システムの一部の間でデータのコンテナをまわりに移動することの共通のテクニックです。 その考え方は、コンテキストがJava層の間のデータの『キャリヤー』であるということです（あるいは、あなたプログラマー）、そして、テンプレート層（またはデザイナー）。 プログラマーとしてのあなたは、いろいろなタイプ（あなたのアプリケーションが要求するものは何でも）のオブジェクトを集めることになって、コンテキストでそれらを置くことになります。 デザイナー、これらのオブジェクトと彼らのメソッドに、そして、プロパティは referencesと呼ばれているテンプレート要素を通してアクセス可能になることになります。 通常、あなたはデータがアプリケーションのために必要とすると決定するデザイナーと働くことになります。 ある意味では、あなたがテンプレートでアクセスにデザイナーに設定されるデータを生産するので、これは『API』になることになります。 したがって、開発プロセスのこのフェーズで、それは若干の時間と慎重な分析を捧げる価値があります。

Velocityがサポート特別なニーズとテクニック（直接（例えば）LDAPサーバーにアクセスするコンテキストのような）にあなた自身のコンテキスト・クラスを作成するためにあなたを許すが、VelocityContextと呼ばれている良い基本の実装クラスは配布の一部としてあなたに対して用意されています。

VelocityContextは全ての一般的な目的ニーズにふさわしいです、そして、我々はあなたがそれを使うと強く推奨します。 例外的で先進の場合のみ、あなたがあなた自身のコンテキスト実装を拡張するか、 つくる必要があります。

VelocityContextを使うことは、標準的なJava Hashtableなクラスを使用するのと、同じくらい単純です。 インタフェースが他の役に立つメソッドを含むが、あなたが使うことになる2つの主なメソッドはあります

	public Object put(String key, Object value); public Object get(String key);

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を経た大きいデータ・セット）を使用する良い理由があります、しかし、それが避けられることができるならば、何か他を使うよりよいかもしれません。 『直接』に、我々は何かをすることを意味しました：

	Vector v = new Vector(); v.addElement("Hello"); v.addElement("There"); context.put("words", v.iterator() );

ここで、Iteratorがコンテキストに置かれるところ。 その代わりに、あなたが単に行います：

	context.put("words", v );

それから、全ては洗練された： Velocityはその（リスト経由で）Vector実装コレクションを理解して、したがって、iterator()メソッドを見つけることになります、そして、各時その使用のために『新しい』Iteratorのためにそれを得るそれが必要とする使用はそうします。 普通のIteratorだけで（...より上の最初の切れっぱし）一旦velocityが#foreach()でそれを使うならば、Velocityにはそれが使われる次の#foreach()の用途に、新しいものを得ることの方法がありません。 結果は、そのリファレンスを使っている少しの以降の#foreach()ブロックからもの出力ではありません。

上のこれは、Velocityでコレクションについて繰り返すことは素晴らしい心配を必要として、考えた何かであるという印象を与えるはずではありません。 むしろ、一般に、正反対は真実です。 あなたがコンテキストにIteratorを置くとき、慎重にするだけでください。

Context Chaining

Velocityのコンテキスト・デザインの革新的な機能は、context chainingの概念です。 また、時々context wrappingと呼ばれて、この先進の機能は、それをテンプレートに1つの『隣接する』コンテキストとして現れさせる方法において、一緒に別々のコンテキストを接続するためにあなたを許します。

これは、例で一番良く示されます：

	VelocityContext context1 = new VelocityContext(); context1.put("name","Velocity"); context1.put("project", "Jakarta"); context1.put("duplicate", "I am in context1"); VelocityContext context2 = new VelocityContext( context1 ); context2.put("lang", "Java" ); context2.put("duplicate", "I am in context2"); template.merge( context2, writer );

上のコードにおいて、我々は上に向かうcontext2にそれがcontext1をchainsするようなものを課しました。 テンプレートでのそれ、あなたがそうすることができるこの手段少しもオブジェクトを加えるために使われるキーの重複がない限り、2つのVelocityContextオブジェクトのどちらにでも入れられたアイテムのアクセス。 それが場合であるならば、そのままに重要な『複製』のためにより上に、チェーンにおいて最も近いコンテキストで保存されるオブジェクトは利用できることになります。 上のこの例で、オブジェクトは「I am in context2」という文字列が返される。

この重複または『covering』がコンテキスト・アイテムの少しの方法にもおいてしないという注意は、おおわれたオブジェクトを害するか、変えます。 上の例でそうストリング「私は、context1でいます」生きてよくcontext1.get("duplicateを通してさらにaccessableである」）。 上の例で以外、テンプレートでのリファレンス『$duplicate』の値はす『私は、context2でいます』、そして、テンプレートはおおわれたひもにアクセスをしません『私は、context1でいます』。

あなたがあなたが情報をあなたがそうすることになるコンテキストに加えるためにテンプレートに頼っている時が翻訳の後のそれ以後を調べるように注意しなければならない点にまた、注意してください。 テンプレートでの#set()ステートメントを経たコンテキストへの変更点は、外のコンテキストだけに影響を及ぼすことになります。 それで、テンプレートからデータが内部のものの上へ置かれたのを期待して、あなたが外のコンテキストを捨てないことを確認してください。

この機能は多くの使用を持ちます、最も共通のものはこれまで提供している階層化されたデータ・アクセスとtoolsetsです。

前に言及されるので、このガイドの現在の範囲を越えて以外、Velocityコンテキスト仕組みはまた、 拡張可能です。 あなたが興味を起こすならば、提供されたコンテキストがどのようにまとめられるかについて見るために、パッケージorg.apache.velocity.contextでクラスを見てください。 Futher、支持記憶としてデータベースを使う[ goofy ]ものを含む交互の実装を示す配布において、2、3の例が、examples/context_exampleディレクトリにあります。

に注目してください、これらの例は、サポートされていなくて、デモンストレーション/教育的な目的だけのためにそこにあることに注意してください。。

Objects Created in the Template

Javaコードがオブジェクトを扱わなければならないところがつくった2つの共通の状況が、テンプレートで実行時にあります：

テンプレート作者がJavaコードによってコンテキスト内に位置する オブジェクトのメソッドを呼び出すとき

	#set($myarr = ["a","b","c"] ) $foo.bar( $myarr )

テンプレートはオブジェクトをコンテキストに加えるとき、Javaコードはそれらのオブジェクトにアクセスすることができ、その後マージ処理が完了します。

	#set($myarr = ["a","b","c"] ) #set( $foo = 1 ) #set( $bar = "bar")

Dealing with these cases if very straighforward, as there are just a few things to know:

これらの場合を扱うには、とても単純で2、3の事柄を知っていればよい:

• コンテキストで置かれるか、メソッドにパスされるとき、VTL 範囲オペレータ [ 1..10 ] と ObjectArray [「a」（b）」] は java.util.ArrayList オブジェクトです。 したがって、テンプレートでつくられる配列を受け入れるようにできているあなたのメソッドは、これを考慮して書く必要があります。
• 数字はコンテキストでの Integer になります、そして、もちろん、文字列は Strings になります。
• Velocity will properly 'narrow' args to method calls, so calling setFoo( int i ) with an int placed into the context via #set() will work fine.
• Velocityはメソッド呼び出しに正しくargsを『狭くする』ので、#set()を通してコンテキストに置かれるintでsetFoo( int i )を呼ぶことはきれいに動作することになります。

Other Context Issues

VelocityContext（またはAbstractContextに由来するどんなコンテキストでも）によって提供される機能のうちの1つは、キャッシュしているノード特定のイントロスペクションです。 一般にあなた開発者あなたのコンテキストとしてVelocityContextを使うとき、これについて心配する必要がありません。 しかし、この機能のについて知っておいて欲しい既知の使い方のパターンがあります。

それがノードを訪問するので、VelocityContextはテンプレートで構文ノードに関するイントロスペクション情報を蓄積することになります。 そして、以下の状況では：

• あなたは、同じVelocityContextを使っている同じテンプレートの上に、オブジェクトを繰り返しています。
• Template キャッシュはオフです。
• あなたはイテレートごとのgetTemplate()からのTemplateを要求します。

あなたのVelocityContextがメモリ「リーク」（それは、本当に集まっているより多くのイントロスペクション情報だけです。）をするように見えることになることはあり得ます 起こることはそれが訪問する各テンプレートのために、それがテンプレート・ノードintrospection情報を蓄積するということです、そして、キャッシュしているテンプレートが離れてそうであるので、それが各時新しいテンプレートを訪問していることはVelocityContextに現れます。 それゆえに、それはより多くのintrospection情報を集めて、成長します。 あなたが以下のうちの1つ以上をすることを特に推奨します。:

• Create a new VelocityContext for each excursion down through the template render process. This will prevent the accumulation of introspection cache data. For the case where you want to reuse the VelocityContext because it's populated with data or objects, you can simply wrap the populated VelocityContext in another, and the 'outer' one will accumulate the introspection information, which you will just discard. Ex. VelocityContext useThis = new VelocityContext( populatedVC ); This works because the outer context will store the introspection cache data, and get any requested data from the inner context (as it is empty.) Be careful though - if your template places data into the context and it's expected that it will be used in the subsequent iterations, you will need to do one of the other fixes, as any template #set() statements will be stored in the outermost context. See the discussion in Context chaining for more information.
• テンプレート・レンダリング・プロセスによって軌跡を下っていく毎に新しいVelocityContextを作成してください。 これは、イントロスペクション・キャッシュ・データの蓄積を防ぐことになります。 あなたがVelocityContextを再利用したい場合のために、データまたはオブジェクトで住みます、あなたは単に住まれたVelocityContextを中で包むことができます別の、そして、『外の』ものはintrospection情報を蓄積することになります。そして、あなたはそれを捨てることになるだけである。 Ｘ。 VelocityContext useThis =新しいVelocityContext( populatedVC）; この作業外のコンテキストがそうすることになる、ストアintrospectionが、データをキャッシュして、内部のコンテキスト（そのままに空にしてください。）から、どんな要請されたデータでも得ます 慎重です−コンテキストとそれへのあなたのテンプレート立場データがそうな、それが以降の繰り返しにおいて使われることになることを予想します、あなたは他のうちの1つをする必要があることになりますどんなテンプレート#set()ステートメントでも最も外部のコンテキストに保存されることになるので、修理します。 詳細はContext chainingで議論を見てください。
• Turn on template caching. This will prevent the template from being re-parsed on each iteration, resulting the the VelocityContext being able to not only avoid adding to the introspection cache information, but be able to use it resulting in a performance improvement.
• キャッシュしているテンプレートの変化。 これは、テンプレートを防ぐことになりますから各繰り返しに関してre-parsedしました結果として起こますintrospectionキャッシュ情報を増すことを避けるだけでなくて、それを使うことができもすることができるVelocityContextパフォーマンス改良での結果として起こます。
• Reuse the Template object for the duration of the loop iterations. Then you won't be forcing Velocity, if the cache is turned off, to reread and reparse the same template over and over, so the VelocityContext won't gather new introspection information each time.
• テンプレート・オブジェクトをループ繰り返しの継続期間に再生利用してください。 それから、キャッシュがrereadとreparseにオフにされるならば、あなたはVelocityを強制していることにはならなりません何度も、VelocityContextが各時新しいintrospection情報を集めることにはならならないように同じテンプレート。

Servlet Programming

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つのhandleRequest()メソッドのより新しいものです。 そして、バージョン1.1において実装されます。 このメソッドとの違いは、Contextと同じように、HttpServletRequestとHttpServletResponseオブジェクトがメソッドに対する引数としてあなたに渡されるということです。 他の違いはこのメソッドが全ての処理がメソッドによって取り扱われたことを明らかにするためにnullを返すことができるということです、そして、そのVelocityは呼び出しrequestCleanup()以外は何もしません。 そして、あなたは、例えば、要求をリダイレクトしたいという場合には、 これはとても役に立ちます。

いつものように、最も確実で最新の注意事項のためには、 Javadoc APIドキュメンテーションを参照してください。

以下のコードは、例ディレクトリにおいて配布に含められるSampleServlet.javaクラスと 同じ物です。

	public class SampleServlet extends VelocityServlet { public Template handleRequest( HttpServletRequest request, HttpServletResponse response, Context context ) { String p1 = "Jakarta"; String p2 = "Velocity"; Vector vec = new Vector(); vec.addElement( p1 ); vec.addElement( p2 ); context.put("list", vec ); Template template = null; try { template = getTemplate("sample.vm"); } catch( ResourceNotFoundException rnfe ) { // couldn't find the template } catch( ParseErrorException pee ) { // syntax error : problem parsing the template } catch( Exception e ) {} return template; } }

見覚えがありますか？ コンテキスト・オブジェクトを作成することを除いては、VelocityServletベースクラスによってあなたのために完了していますまた、VelocityServletベースクラスによってあなたのためにmerge()ステップを行います、これは我々がこのガイドの初めに言及した基本的なコード・パターンと同じです。 我々は、コンテキストを取り出し、我々のアプリケーション・データを加えて、テンプレートを返します。

handleRequest()メソッドに渡されるデフォルトのContextオブジェクトは、現在のHttpServletRequestとHttpServletResponseオブジェクトを含みます。 これらは、コンテキストで置かれて、定数VelocityServlet.REQUEST（値=『req』）と VelocityServlet.RESPONSE（値=『res』）を使います。 あなたのJavaコードにおいてアクセスするためには、これらのオブジェクトを使用します：

	public Template handleRequest( Context context ) { HttpServletRequest request = (HttpServletRequest) context.get( REQUEST ); HttpServletResponse response = (HttpServletResponse) context.get( RESPONSE ); ...

そして、あなたのテンプレート:

	#set($name = $req.getParameter('name') )

より高度な使い方として、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ファイルに加えてください：

	<servlet> <servlet-name>MyServlet</servlet-name> <servlet-class>com.foo.bar.MyServlet</servlet-class> <init-param> <param-name>properties</param-name> <param-value>/velocity.properties</param-value> </init-param> </servlet>

全てが正しいと仮定して、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 )
  プロパティ・キーの値を返します。 注意: それらは String 以外のものでありえるので、あなたは戻り値のタイプを 知っていなければなりません。
• init()
  配布において提供されるデフォルトのプロパティによる実行時を初期化します。 （これらは、プロパティに関連するセクションの中の下でリストされます。）
• init( Properties p )
  引数として渡されるjava.util.Propertiesオブジェクトに含まれるプロパティで、 実行時に初期化します。
• init( String filename )
  プロパティを使っている実行時がプロパティ・ファイル・ファイル名で見つけた プロパティで実行時に初期化します

注意: それぞれの場合、デフォルトプロパティは、基底の設定として使用され、 独自の値が、デフォルトのプロパティに上書きされます。 つまり、オーバーライドされないどんなデフォルトのプロパティでも、 実質的に残ることになります。 これは、完全なセットよりむしろあなたが変更したい部分のプロパティだけ 指定できるという利点があります。

Velocityを初期化するのに最も共通の方法は、このようになります：

1. あなたが望む設定値をorg/apache/velocity/runtime/defaults/velocity.properties（デフォルトのセット）と同じフォーマットの中のファイルに置くか、またはjava.util.Propertiesにおいて、それからinit( filename )またはinit( Properties )を呼び出します。
2. setProperty()を個々に使って設定値をセットしてください、それから、 init()を呼んでください。 このメソッドが、一般にすでに彼ら自身の構成管理システムを持つようなより高度なアプリケーションによって使われます − これは、例えばそれが実行時に生成する値に基づくVelocityを設定するようなアプリケーションを許します。

一旦、実行時に初期化されるならば、あなたはそれであなたが願うものをすることができます。 これは大部分は出力ストリームにテンプレートをレンダリングする周囲を循環します。 そして、Velocityユーティリティ・クラスは簡単にこれをするためにあなたを許します。 現在、メソッドとそれらがするものの簡潔な説明は、ここにあります：

• evaluate( Context context, Writer out, String logTag, String instring )
evaluate( Context context, Writer writer, String logTag, InputStream instream )
  これらのメソッドは、 String 形式か 出力 Writer への InputStream において、あなたが提供するコンテキストを使って、入力をレンダリングします。 これは、文字列のトークン置換や、データベースのようにVTLを含んだ内容の 「テンプレート」を保持したり、その他のファイル以外の格納をしたり、 動的に作成したりするために使うには非常に便利なメソッドです。
• invokeVelocimacro( String vmName, String namespace, String params[], Context context, Writer writer )
  Velocimacrosへの直接のアクセスを許します。 あなたが望むならば、これはまた、上のevaluate()メソッドによって完成していることがありえます。 ここでは、あなたは単にあなたが呼ばれることを望むvmに名をつけ、 VMに渡す引数の配列、データのContext、出力のためのWriterを作成します。 注意: VM 引数はコンテキスト（arg.として使われる文字通りのデータよりむしろ）でのデータ・オブジェクトの『キー』でなければなりません。 これは、多分変わることになるでしょう。
• mergeTemplate( String templateName, Context context, Writer writer )
  標準的なテンプレートのハンドリングとVelocityのレンダリング・サービスへの 便利なアクセス。 このメソッドは、テンプレートを得て、レンダリングすることの世話します。 それは、ファイル・リソース・ローダーのためにプロパティ設定によってテンプレートをロードすることを利用することになって、したがって、ファイルの利点を提供して、そのVelocity申し込みをキャッシュしているテンプレートを解析しました。 あなたが特別なニーズを持たない限り、これはアクセス・テンプレートに最も効率的な方法であって、推薦されます。
• boolean templateExists( String name )
  テンプレートnameが現在設定されたリソース・ローダーで見つけることができるかどうか判断します。

一旦我々がこれらの基本のヘルパーを知るならば、Velocityを使うJavaプログラムを書くことは簡単です。 ここでは、：

	import java.io.StringWriter; import org.apache.velocity.app.Velocity; import org.apache.velocity.VelocityContext; public class Example2 { public static void main( String args[] ) { /* まずは、実行時エンジンを初期化する。デフォルトでよい。 */ Velocity.init(); /* Context を作成して、それにデータを入れる */ VelocityContext context = new VelocityContext(); context.put("name", "Velocity"); context.put("project", "Jakarta"); /* テンプレートをレンダリングする */ StringWriter w = new StringWriter(); Velocity.mergeTemplate("testtemplate.vm", context, w ); System.out.println(" template : " + w ); /* レンダリング用に独自の文字列を作成する */ String s = "We are using $project $name to render this."; w = new StringWriter(); Velocity.evaluate( context, w, "mystring", s ); System.out.println(" string : " + w ); } }

我々は、このプログラムを実行して、我々のプログラム（我々がデフォルトの構成プロパティとdefaulを使ったので、テンプレートをロードする場所は現在のディレクトリです）と同じディレクトリにおいて、テンプレート testtemplate.vmを持ちます、我々の出力は、こうなるはずです：

	template : Hi! This Velocity from the Jakarta project. string : We are using Jakarta Velocity to render this.

そこで我々が使ったテンプレート（testtemplate.vm）は 以下のようになります。

	Hi! This $name from the $project project.

これでここにあるもの全てです! 我々のプログラムでmergeTemplate()とevaluate() を使う必要はなかったことに注意。 それには、デモンストレーション目的のために両方とも含まれます。 あなたは多分メソッドのうちの1つだけを使うことになるでしょう、 アプリケーション必要条件以外は、あなたがやりたいようにして構いません。

これはこのガイドの初めに言及された『基本的パターン』と少し異なるように見えます、 しかし、それは本当に同じものです。 最初に、あなたはコンテキストを作って、それを必要とされるデータで満たしています。 そこで、この例で異なっているのは、mergeTemplate()を使用して いる部分す。mergeTemplate()は、Runtimeクラスの低レベルの呼び出しを 利用して、あなたのためにテンプレートの取得とマージを行なっています。 第二の例では、あなたが String 経由で動的にあなたのテンプレートを作っていること、 そのため、処理の部分で『テンプレートを選びます』のためのanalgousで、 evaluate()メソッドの一部は、あなたのために 低レベルの呼び出しを使ってマージを行ないます。

それで、上記の例はVelocityテンプレートエンジンを使用するパターンを単純な ままにしていますが、ユーティリティ機能が繰り返しのコツコツした作業や、その他のテンプレートファイルの内容をテンプレートにするオプションなど行なっています。

Exceptions

Velocityが、解析/マージのサイクルで投げることになる3つの例外があります。 また、I/Oの問題、その他からやって来ることになる例外がこれに追加されます。 それらは、パッケージorg.apache.velocity.exceptionで見つけられます：

1. ResourceNotFoundException
   リソース管理システムが要請されたリソース（テンプレート）を見つけることができない時に投げられます。
2. ParseErrorException
   リソース（テンプレート）を解析するとき、VTL構文エラーが発見された時に投げられます。
3. MethodInvocationException
   レンダリング時にコンテキスト内のオブジェクトのメソッドで例外を投げられました。 この例外は、アプリケーションに投げられた例外とpropogatesにそれをラップします。 これは、実行時であなた自身のオブジェクトにおいて問題を取り扱うためにあなたを許します。

それぞれの場合、メッセージは実行時ログに入れられます。 詳細は、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つのプロパティ・ファイルにあなたのアプリのためにプロパティの全てを結合する自由を与えます。

我々がテンプレートフォームをロードするのにカレントディレクトリではなく、 異なるディレクトリを使いたい場合には、このようにします：

	... import java.util.Properties; ... public static void main( String args[] ) { /* まずは、実行エンジンを初期化する */ Properties p = new Properties(); p.setProperty("file.resource.loader.path", "/opt/templates"); Velocity.init( p ); /* Contextを作ってデータを入れる */ ...

そして、ディレクトリ/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 を参照しています。

	... import org.apache.velocity.app.event.EventCartridge; import org.apache.velocity.app.event.ReferenceInsertionEventHandler; import org.apache.velocity.app.event.MethodExceptionEventHandler; import org.apache.velocity.app.event.NullSetEventHandler; ... public class Test implements ReferenceInsertionEventHandler, NullSetEventHandler, MethodExceptionEventHandler { public void myTest() { .... /* * まぁ、Testクラスの実装では、イベントハンドラインタフェースを * サポートするように正しくメソッドが実装されてると仮定します。 * これらを使うにはまず、cartridgeを新しく作ります。 */ EventCartridge ec = new EventCartridge(); /* * そして、このクラスをそのハンドラーに収容するように登録します */ ec.addEventHandler(this); /* * それから、最後にcontextを自身に追加します。 */ ec.attachToContext( context ); /* * さて、通常の作業としてコンテキストをテンプレートにマージする */ .... } /* * そして、イベントハンドラを実装 */ public Object referenceInsert( String reference, Object value ) { /* なにかする */ return value; } public boolean shouldLogOnNullSet( String lhs, String rhs ) { if ( /* 何らかのルール */ ) return false; return true; } public Object methodException( Class claz, String method, Exception e ) throws Exception { if ( /* 何らかのルール */ ) return "I should have thrown"; throw e; } }

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にすると良いでしょう。 デバッグ時には、とても役立ちます。

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プロパティが適用されます。 これは、リロード制御の便宜のためのキャッシュ機能の制御を許可します。 テンプレートが頻繁に更新され、 アプリケーションに戻ったり、サーブレットエンジンにその機能を 望んでいない場合や許可されていない場合などに ホスティング環境やIPS環境で役に立ちます。

<name>.resource.loader.modificationCheckInterval = 2
これは、キャッシュがオンにされたときに、修正がされたかチェックする間隔を 秒数で指定します。この数字が > 0 の場合、テンプレートが修正されたか チェックする間隔を秒であらわしています。もしテンプレートが最後にチェック したときから変更されていれば、それは再ロードされて、再解析されます。 そうでなければ、何もしません。 また、この数字が <= 0 のとき、修正チェックは行なわれません、プロパティ cache(上)が true と仮定するとテンプレートを最初にしようする ときに一度だけ、読み込まれ解析され、それはアプリケーションやサーブレットエンジンが リスタートされるまでチェックやリロードはされません。

実例を示すために、ここで、例が、FileResourceLoaderをセットアップすることはどのように管理されるかについて示して、デフォルトのVelocityプロパティからのとられます

	resource.loader = file file.resource.loader.description = Velocity File Resource Loader file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader file.resource.loader.path = . file.resource.loader.cache = false file.resource.loader.modificationCheckInterval = 2

Velocimacro

velocimacro.library = VM_global_library.vm
複数値のキー。CSV形式の値を受け入れます。 Velociry 実行時エンジンが開始したときに、ロードされる Velocimacroライブラリのファイル名です。これらのVelocimacroは、 すべてのテンプレートでアクセスすることができます。ファイルは ファイルローダーリソースパスのrootからを仮定しています。

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でローカル範囲であることになるかどうか制御します。

String Interpolation

runtime.interpolate.string.literals = true
VTL String リテラルの展開の仕組みを制御します。 VTL StringLiteralは、特に一般に#set()ステートメント、リファレンスのメソッド呼び出し、 VMへのパラメータにおいてまたは指示的なVTLへの引数として使われる二重の引用符を使っているストリングであるという注意。 詳細はVTLリファレンスを見てください。

Runtime Configuration

parser.pool.size = 20
このプロパティは、Velocityが起動時に作成して、プールに保持する パーサの数を設定します。 デフォルトでは、20のパーサーですが、たいていの使用のでは十分なはずです。 Velocityがパーサーを使い果たすと、ログに記録され、必要に応じてそれらが 作成されます。 ただし、それらはプールに加えられないことに注意してください。 これは、標準的なパーサーのプールと比較して遅い操作ですが、 これは例外的な状態です。あなたがログ・メッセージに出ている場合には、 このプロパティの数字を増やしてください。

Velocityには、シンプルで柔軟性を兼ね備えてた素晴らしい2,3のロギング機能があります。 どんな特別な設定をしなくても、Velocityは、ファイルベースのログに すべてのログメッセージをVelocityがインストールされた「カレントディレクトリ」 ににvelocity.logという名前のファイルで出力します。 より高度な使い方をするユーザーのために、あなたは、 あなたの現在のロギングの機能に対してVelocityの全てのログメッセージを 統合させるかもしれません。

あなたのオプション

• Default Configuration
  デフォルトで、Velocityは、ファイルベースのログをカレントディレクトリに作成します。
• Custom Standalone Logger
  あなたは、カスタムロギングクラスを作成することができます。− あなたは単にインタフェースorg.apache.velocity.runtime.log.LogSystemを実装しなければならなくて、それから単に構成プロパティruntime.log.logsystem.classにクラス名を設定し、そして、Velocityはinit時にそのクラスのインスタンスを作ります。 あなたが他のプロパティも指定するために、あなたは別のクラス名を指定するかもしれません。 詳細については、 Velocity helper classと configuration keys and values.を参照してください。
• Integrated Logging
  単にorg.apache.velocity.runtime.log.LogSystemインタフェースを実装することによって、あなたはVelocityのロギング機能をあなたのアプリケーション現存のロギング・システムと統合することができます。 それから、あなたがinit()を呼ぶ前にruntime.log.logsystem構成キーによって、Velocityにクラスをロギング・インスタンスを渡してください、そして、Velocityはあなたのアプリケーションloggerにメッセージをロギングすることになります。 詳細は、 Velocity helper classと configuration keys and valuesを参照してください。

とっても単純ならば、カスタムloggerを作ります。 下のコードは、あなたがあなた自身のアプリケーションにおいてこれをするかもしれない方法の単純なスケッチです。

Simple Example of a Custom Logger

これは、あなたの独自のアプリケーションでVelocityのロギングシステムを統合する 方法の簡単な例です。

	import org.apache.velocity.runtime.log.LogSystem; ... public class MyClass implements LogSystem { ... public MyClass() { ... try { /* * このクラスをloggerをとして登録 */ Velocity.setProperty(Velocity.RUNTIME_LOG_LOGSYSTEM, this ); Velocity.init(); } catch (Exception e) { /* * なにか行なう */ } } /** * これはVelocity用にログメッセージ付きで呼び出すようにあなたが実装したメソッド。 */ public void logVelocityMessage(int level, String message) { /* なにかする */ } ... }

Velocityについての基本的で重要な部分のうちの1つは、 リソース管理システムとリソース・ローダーです。 リソース管理システムがまた、非テンプレートリソース（特に#include()指示を通してロードされるもの）を取り扱うことになるので、彼らは『テンプレート』よりむしろ『リソース』とここで呼ばれます。

非常に柔軟なリソース・ローダー・システムは非常に柔軟なので、同時に、 一つ以上のリソース・ローダーを指定することができます。 これは設定とリソース管理において相当な柔軟性を許します、そしてさらに、 あなたの特別な要求のためにあなた自身のリソース・ローダーを書ことができます。

現在、下記で説明される4種類のリソースローダーがVelocityに含まれます。 注意: サンプル設定プロパティでは、ローダーの共通名が示されます( 例えば、'file'は、file.resource.loader.pathの「file」)。 この「共通名」は、あなたの設定では働かないかもしれません。 このシステムがどのように機能するかについて理解するために、 リソース設定プロパティに関するセクションを参照してください。 また、これらのローダーの各々は、パッケージorg.apache.velocity.runtime.resource.loaderにあります。

• FileResourceLoader : このローダーはファイルシステムからリソースを得る。その設定プロパティは以下が含まれる:
  • file.resource.loader.path = <path to root of templates>
  • file.resource.loader.cache = true/false
  • file.resource.loader.modificationCheckInterval = <seconds between checks>
  これは、デフォルトのローダーであって、『現在のディレクトリ』からデフォルトでテンプレートを得るために、構成されます。 servletsでVelocityを使うことの場合、あなたがあなたのテンプレートをあなたがあなたのservletエンジンを始動するディレクトリに保たなければならなくしたくないので、これは問題でありえます。 詳細はVelocityでservlet開発セクションを見てください。
• JarResourceLoader : このローダーは、特定のjarファイルからリソースを得ます。 あなたは、便宜上jarにあなたのテンプレートをまとめることを除いて、 それはFileResourceLoaderに非常に類似しています。 jar.resource.loader.pathを除いて、プロパティは同一です、そこで、あなたはあなたがそこからリソースをロードしたいjar(s)のフルパスを提供します。 loader.path 用に jar を指定するために、あなたはjava.net.JarURLConnectionの標準のjar URL構文を使います。
• ClasspathResourceLoader : このローダーは、classloaderからリソースを得ます。 classpathは一般に素晴らしい苦労と苦しみの出所であるが、Servlet仕様2.2に対応したservlerランナーを動かすとき、それは非常に役に立つ仕組みです。 Tomcatは、その一例です。 あなたがしなければならない全てがjarであって、 効果的にこのローダーを使用するためには、あなたのテンプレートをすべてjarにして、 そのjarをあなたのWebアプリケーションのWeb-INF/libディレクトリに入れてください。 設定オプションについて心配する必要はありませんし、絶対パスと相対パスの問題に ついても、JarとFileリソースローダーとなります。
• DataSourceResourceLoader : このローダーは、データベースのようなDataSourceからリソースをロードすることになります。 それがJ2EEサポートを必要とするので、標準の部分がビルドでは、このローダーは構築されません。 このローダーをビルドするためには、どうかJ2EE配布をダウンロードして、build/libディレクトリへのj2ee.jarを移動して、それからビルドするために、jar-j2eeというビルドターゲットを使用して新しいvelocity jarを構築します。 このローダーの詳細については、クラスorg.apache.velocity.runtime.resource.loader.DataSourceResourceLoaderについてはjavadocを見てください。

Configuration Examples

Velocityのためにリソース・ローダーを設定することは簡単です。 制御のプロパティで、詳細はリソース設定セクションでリストされています。

一つ以上のリソース・ローダーを設定することにおける最初のステップは、 Velocityへの名前によるそれらを『宣言します』。 プロパティresource.loaderを使ってください、そして、一つ以上のローダー名をリストしてください。 あなたはあなたが欲しい何でも使うことができます−これらの名前が構成与えられたローダーと関連するために使われます。

	resource.loader = file

そのエントリは、我々が「file」として知られているリソース・ローダーを 持つことになると宣言します。 次にすることは、重要なプロパティをセットすることです。 一番大事なのは、ローダーとして使用するクラスを宣言することです：

	file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader

この場合、我々は Velocity に対して、「file」というリソースローダーを 設定し、それが org.apache.velocity.runtime.resource.loader.FileResourceLoader クラスを使用することを設定します。 次に、このローダーにとって重要なプロパティを設定します。

	file.resource.loader.path = /opt/templates file.resource.loader.cache = true file.resource.loader.modificationCheckInterval = 2

ここでは、我々は2、3のものを設定しました。 最初に、テンプレートを見つけるためのパスとして/opt/templates を設定しました。 第二に、我々はキャッシュすることをオンにしました、そのため、 テンプレートまたは静的ファイルが読まれたあと、それはメモリにキャッシュされます。 そして、最後に、我々は新しいテンプレートのために更新チェック間隔を2秒にセットしました。

それらは、基本です。 以下は、異なる設定の2、3の例です。

何もしないデフォルト設定 : 名前のとおり、デフォルト設定をするので何も行なう必要はありません。 この設定はデフォルトのリソース・パスとして現在のディレクトリで FileResourceLoader を使います、そして、キャッシュは offです。 プロパティ・セットとして、次のように表されます：

	resource.loader = file file.resource.loader.description = Velocity File Resource Loader file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader file.resource.loader.path = . file.resource.loader.cache = false file.resource.loader.modificationCheckInterval = 0

複数テンプレートパス設定 : テンプレートの検索パスを「ノード」として複数のディレクトリを検索するように FileResourceLoader を使用するように設定します。 また、キャッシュを使い、テンプレートを10秒間隔で変更点があるかチェックします。 プロパティ・セットとして、次のように表されるます：

	resource.loader = file file.resource.loader.description = Velocity File Resource Loader file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader file.resource.loader.path = /opt/directory1, /opt/directory2 file.resource.loader.cache = true file.resource.loader.modificationCheckInterval = 10

複数ローダー設定 : この設定は、同時に3つのローダー、FileResourceLoader、ClasspathResourceLoader と JarResourceLoaderをセットアップします。 ローダーは、最初に FileResourceLoader が参照され、それから ClasspathResourceLoader と最終的に JarResourceLoader と設定されます。 即座にテンプレートを置換するためにファイル・テンプレート領域に落とすことで 通常 jar 経由のものがクラスパス上でテンプレートが見つかるので jarを作り直さなくてもよくなります。

	# # 3つのリソースローダーを使うことを指定 # resource.loader = file, class, jar # # 'file'と名づけたローダーでは、使用するクラスとして FileResourceLoaderをセットして # キャッシュを off にして、 テンプレート用に3つのディレクトリを使用する # file.resource.loader.description = Velocity File Resource Loader file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader file.resource.loader.path = templatedirectory1, anotherdirectory, foo/bar file.resource.loader.cache = false file.resource.loader.modificationCheckInterval = 0 # # 'class'と名づけたローダーでは、ClasspathResourceLoader を使用する # class.resource.loader.description = Velocity Classpath Resource Loader class.resource.loader.class = org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader # # 最後に、'jar'と名づけたローダーでは、JarResourceLoader を使用し、 # 2つのjarから読み込む # jar.resource.loader.description = Velocity Jar Resource Loader jar.resource.loader.class = org.apache.velocity.runtime.resource.loader.JarResourceLoader jar.resource.loader.path = jar:file:/myjarplace/myjar.jar, jar:file:/myjarplace/myjar2.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文書から始めると：

	<?xml version="1.0"?> <document> <properties> <title>Developer's Guide</title> <author email="geirm@apache.org">Velocity Documentation Team</author> </properties> </document>

ここで、次のようにコードを取り込む小さなJavaプログラムを作成します。

	... SAXBuilder builder; Document root = null; try { builder = new SAXBuilder( "org.apache.xerces.parsers.SAXParser" ); root = builder.build("test.xml"); } catch( Exception ee) {} VelocityContext vc = new VelocityContext(); vc.put("root", root ); ...

（このやる方についての詳細は、配布のexamplesディレクトリにあるAnakiaサンプルを参照してください。） さて、通常の Velocity テンプレートを作ります：

	<html> <body> The document title is $root.getChild("document").getChild("properties").getChild("title").getText() </body> </html>