サーブレットの設定 (web.xml) には、表示処理を実行する Velocity ベースのサーブレットへの参照を含めるよう変更しなければなりません。 全ての *.vm ファイルはこのサーブレットへマッピングされます。 このサーブレットにより、Request, Session, Application スコープ、 さらに toolbox.xml ファイルで指定されているツール群が 'context' へ設定されます。 このサーブレットはテンプレートを表示するためにこのコンテキストのデータと、 Velocity エンジンを使用します。

注: 機能追加はこのサーブレットをサブクラス化することで実現でき、 このことについては VelocityLayoutServlet でさらに言及します。

web.xml

<!-- Velocity テンプレートコンパイラを定義 -->
<servlet>
  <servlet-name>velocity</servlet-name>
  <servlet-class>
    org.apache.velocity.tools.view.servlet.VelocityViewServlet
  </servlet-class>

  <init-param>
    <param-name>org.apache.velocity.toolbox</param-name>
    <param-value>/WEB-INF/toolbox.xml</param-value>
 </init-param>

  <init-param>
    <param-name>org.apache.velocity.properties</param-name>
    <param-value>/WEB-INF/velocity.properties</param-value>
 </init-param>

 <load-on-startup>10</load-on-startup>
</servlet>

<!-- *.vm ファイルを Velocity にマッピングする -->
<servlet-mapping>
  <servlet-name>velocity</servlet-name>
  <url-pattern>*.vm</url-pattern>
</servlet-mapping>

Velocity の設定は 任意 であり、 多くのアプリケーションではデフォルト設定で動作します。 velocity.properties ファイルはロギング、 エンコーディング、マクロの設定を含みます。

デフォルトの設定では、 'グローバル' な Velocimacro テンプレートの配置情報が指定されています。 このファイルには全てのテンプレートから利用できるマクロが含まれます。

この設定ファイルの場所は web.xml で指定します。 また、このファイルは WEB-INF ディレクトリの中に配置するのが良いでしょう。 サンプルの設定ファイルは配布物に含まれています。

Velocity の設定についての詳細は Velocity ユーザガイド を参照してください。

  velocimacro.library = /WEB-INF/VM_global_library.vm
  velocimacro.permissions.allow.inline = true
  velocimacro.permissions.allow.inline.to.replace.global = false
  velocimacro.permissions.allow.inline.local.scope = false  
  velocimacro.context.localscope = false

サンプルのツールボックスファイル、 WEB-INF/toolbox.xml では、 使用するクラスを好きな名前にマップしています。 これは言うほど難しいものではありません。

友達のジョンに道具箱(toolbox)から 'レンチ' を取り出してもらうことについて考えてみます。 ジョンはどの種類のレンチ (メトリック、パイプ、三日月) が必要なのか、ということだけを知っている必要があります。 レンチをどのように使うかどうかは、彼は知る必要はありません。

Velocity のツールボックスも同じです。 ツールが割り当てられてる名前を指定するだけで、 Velocity エンジンが全ての public メソッドをテンプレートから利用可能にしてくれます。 例えばこのような定義を行うことで、テンプレートで $wrench.getSize() または $wrench.size という呼び出しが可能となります。

PipeWrench.java

public class PipeWrench {
  public String getSize() {
	return "でかいパイプレンチ!";
  }
} 

toolbox.xml

<?xml version="1.0"?>
<toolbox>
  <tool>
     <key>wrench</key>
     <class>PipeWrench</class>
  </tool>
</toolbox>

Tool のスコープ

ツールボックスのサポートは VelocityViewServlet に組み込まれており、 さらにサーブレット環境でのスコープの指定もサポートされています。 ツールは リクエスト, セッション, アプリケーション スコープに配置されます。

ツールに設定したスコープにより、ツールのライフサイクルと、ツールが ViewTool を実装している場合に init(Object) メソッドにどのデータが渡されるかが決定されます:

• アプリケーション スコープのツールは、 一回のみインスタンス化され、全てのリクエストに対し再利用されます。当然、 アプリケーションスコープのツールはスレッドセーフである必要があります。 GenericTools の MathTool がアプリケーションスコープのツールの良い例です。 アプリケーションスコープのツールが ViewTool を実装している場合、 インスタンス化された後に Web アプリケーションの javax.servlet.ServletContext が init(Object) メソッドへ渡されます。
• セッション スコープのツールは一つのセッションにつき 一回インスタンス化され、 同一セッションを持つリクエストに対して再利用されます。 セッションスコープのツールが ViewTool を実装している場合、 セッション作成時にリクエストの ViewContext がinit(Object) メソッドへ渡されます。
• リクエスト はデフォルトのスコープとなります。 toolbox.xml の <tool> にスコープが指定されていない場合、 自動的に リクエスト スコープへセットされます。 このスコープのツールは VelocityViewServlet へリクエストが届くたびにインスタンス化されます。 リクエストスコープのツールが ViewTool を実装している場合、 現在のリクエストの ViewContext が init(Object) メソッドへ渡されます。

ツールのスコープは toolbox.xml にこのように <scope> 要素を追加することによって指定することができます:

<tool>
   <key>math</key>
   <scope>application</scope>
   <class>org.apache.velocity.tools.generic.MathTool</class>
</tool>

Java のクラスを ツールとして自動的にテンプレートへ提供することに加え、 ツールボックスでは任意の String や boolean 、 数値を指定しテンプレートへ提供することが可能です。 フォーマットを以下に示します:

<?xml version="1.0"?>
<toolbox>
  <data type="number">
     <key>app_version</key>
     <value>0.9</value>
  </data>
  <data type="string">
     <key>app_name</key>
     <value>ジョンのツールショップ</value>
  </data>
  <data type="boolean">
     <key>debug</key>
     <value>true</value>
  </data>
</toolbox>

テンプレートでは、ツールやデータは指定されたキー (例: $app_version, $app_name, $debug) によってアクセスすることができます。