S2Velocity

プロジェクト文書

Built by Maven

使用方法

このドキュメントでは、読者はS2Container、Velocity、Velocity Toolsを正しく設定し、VelocityテンプレートをWebアプリケーションのビュー層として使うことが出来ているものと前提において説明します。

ツールボックスとは、簡単に言ってしまえばテンプレートがレンダリングする際に自動的に属性にセットされている一連のインスタンス群のことです。ツールボックスを定義する、とは簡単に言ってしまうと、各ツールについて以下の3点を明らかにすることです。

  • マッピングする属性名
  • ツールのクラス
  • ツールのインスタンスのライフサイクル

S2Velocityを使う際には、以下の2つのツールボックスの定義方法のうち、どちらを使うかを決定し、それに従う形で設定を行う必要があります.

Velocity-Tools互換のXML形式による定義

この定義方法では、Velocity Toolsと同じ、XMLによるツールボックスの定義が使えます。

以下に、web.xmlの設定を示します. S2ContainerServlet の定義はそのままでかまいません。 VelocityViewServletをS2Velocityのものに差し替えるため、以下のような内容を設定します。

web.xml 

        <servlet>
                <servlet-name>velocity</servlet-name>
                <servlet-class>org.seasar.velocity.tools.S2VelocityViewServlet</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>

上記のweb.xmlの例では、/WEB-INF/toolbox.xml が、ツールボックスの定義ファイルとなります。 例えば、以下のようなXMLファイルを準備します

toolbox.xml 

<?xml version="1.0"?>
<toolbox>
  <tool>
    <key>sampleTool</key>
    <scope>request</scope>
    <class>org.seasar.velocity.tools.examples.hello.SampleTool</class>
  </tool>
  .
  .
</toolbox>

詳細な説明は Velocity Tools のドキュメントを参照ください。

  • key に指定された名前が、Velocityでの参照名となります。上記の例では $sampleTool によって参照されます。
  • scope には request , session , application が指定できます。インスタンスのライフサイクルを定義します。
  • class には、ツールクラスのFQCNを記述します。

なお、以下の点で、Velocity Tools 1.3と挙動が異なる(非互換となる)点に注意が必要です

  • parameterタグが使えない
    次バージョンで改善予定です。同様の設定が必要な場合は container を指定して S2Container管理で使えば可能です。

S2Containerのネームスペースによる定義

この定義方法では、'toolbox' というnamespaceを持つコンテナに含まれるコンポーネントすべてがツールボックスとして扱われます. このnamespaceを持つコンテナに含まれるすべてのコンポーネントは、リクエストごとにツールボックスにマッピングされ(getComponentされ)ます。 そのため、例えばdiconファイルによる柔軟なコンポーネント定義、プロパティの設定やライフサイクルの指定が行えることになります。

以下に、web.xmlの設定を示します。 S2ContainerServlet の定義はそのままでかまいません。 VelocityViewServletをS2Velocityのものに差し替えるため、以下のような内容を設定します。

web.xml 

        <servlet>
                <servlet-name>velocity</servlet-name>
                <servlet-class>org.seasar.velocity.tools.S2VelocityViewServlet</servlet-class>
                <init-param>
                        <param-name>org.apache.velocity.toolbox</param-name>
                        <param-value>container</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>

上記のように、org.apache.velocity.toolbox パラメータに対して container を指定するのがポイントです。

実際に、diconファイルを書いてみましょう。以下の例では S2Containerのバージョンは2.4.xを仮定しています。

toolbox.dicon 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR//DTD S2Container 2.4//EN"
        "http://www.seasar.org/dtd/components24.dtd">
<components namespace="toolbox">
    <include path="all_services.dicon" />

        <component name="sampleTool" instance="request" class="org.seasar.velocity.tools.examples.hello.SampleTool" />
        <component name="itemTool" instance="request" class="org.seasar.velocity.tools.examples.dao.ItemTool" />

        <component name="requestCountTool" instance="request" class="org.seasar.velocity.tools.examples.scope.CountTool" />
        <component name="sessionCountTool" instance="session" class="org.seasar.velocity.tools.examples.scope.CountTool" />
        <component name="appCountTool" instance="singleton" class="org.seasar.velocity.tools.examples.scope.CountTool" />
</components>

上記の例に加えて、例えばapp.diconの中でこのdiconファイルをincludeしておくことも必要です。 各コンポーネント定義の name の値がそのままVelocityでの参照名となります (たとえば $appCountTool となります)

また、次の点で注意が必要です。

  • Velocity Tools標準のXML定義における applicationスコープのようなinit挙動はしません。 (そのかわり、S2Containerの機能でServletContextは取得可能です)