1. 前提
2. このガイドの目的
3. テンプレートファイルをどこに置くか?
4. 設定プロパティ
5. スタイルシートはどうするか?
6. Velocity JAR ファイルをどこに置くか?
7. 開発を楽にするには?
8. ビルドプロセス

この簡単なガイドは、Velocity の基本と、Apache Tomcat などの J2EE 環境での Velocity の使い方をすでに十分に理解していることを前提にしています。

Web アプリケーションの Tomcat への配備は WAR ファイルで行なえますが、 Tomcat は起動時に WAR ファイルを展開するため、Velocity エンジンは実行時にディレクトリ構造を使えますし、 ServletContext の getRealPath() メソッドは、 対象となるディレクトリの実際のパスを返せます。

WebLogic は配備した WAR ファイルを展開しないため、 WebLogic で同じ WAR ファイルを配備する場合は、結果は異なり、 ServletContext の getRealPath() メソッドは null を返します。では、この環境で、 プロパティファイル／テンプレート／スタイルシート／Servlet／ビルドプロセスは、 どのように扱えばよいのでしょうか?

この短いガイドはこうした疑問に答えるもので、 これを読めば商用のアプリケーションサーバにおいても Velocity をうまく使えることでしょう。

関連する情報はすべて JavaDoc ドキュメントにありますが、 このクイックガイドがあればすぐに作業を始められることでしょう。

ClasspathResourceLoader は、Servlet エンジンのクラスパスにあるリソースからテンプレートをロードできるので、 テンプレートファイル全てを JAR ファイルに入れて、この JAR ファイル (例えば template.jar) をクラスパス上のリソースとして使えるように WEB-INF/lib に置くのも良いかも知れません。

プロパティファイルはどんな名前でもよいのですが、Velocity サイトの全てのドキュメントやサンプルで velocity.properties という名前を使っているので、このガイドでもこのファイル名を使うことにします。

リソースローダを設定するため、このファイルには以下の2行が必要です。

    resource.loader = class
    class.resource.loader.class = org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader

このファイルには他の設定も含まれています。

velocity.properties はどこに置くか?

velocity.properties は WEB-INF ディレクトリ直下に置き、web.xml に以下の数行を加えます。

<servlet>
  <servlet-name>...</servlet-name>
  <servlet-class>...</servlet-class>
    <init-param>
      <param-name>properties</param-name>
      <param-value>/WEB-INF/velocity.properties</param-value>
    </init-param>
</servlet>

そして、Servlet では以下のように実装します。

  protected Properties loadConfiguration (ServletConfig config) throws IOException, FileNotFoundException  {
    String propsFile = config.getInitParameter(INIT_PROPS_KEY);
    Properties p = new Properties();

    if ( propsFile != null ) {
      InputStream iStream = getServletContext().getResourceAsStream( propsFile );

      if ( iStream != null ) {
        p.load( iStream );
      }
    }

    return p;
  }

スタイルシートについては、テンプレートファイルから相対的にファイルを参照できる限り、 どこに置いてもかまいません。

筆者 (Paw Dybdahl) としては、Web アプリケーションのルートディレクトリの下 (つまり、WEB-INF ディレクトリと同じレベル)に stylesheets という名前のディレクトリを作って、 そこにスタイルシートを置くのがいいと思っています。

テンプレートファイルでは以下のようにスタイルシートを参照します。

<link REL="stylesheet" TYPE="text/css" HREF="./stylesheets/style.css">

まず最初に、Velocity JAR ファイルとして、 依存するライブラリを含まないバージョンを使うか、依存する JAR ファイルを全て含んだバージョンを使うかを決めないといけません。Avalon Logkit、 Common Collections、Jakarta ORO との不整合を気にしないのであれば、 依存するライブラリを全て含む JAR ファイルを使うと非常に便利です。

Velocity JAR ファイルを Web アプリケーションの WEB-INF/lib ディレクトリに置けば、その Web アプリケーションのクラスパスで Velocity の各クラスが使えるようになります。

Velocity を「実際に」使っているとすぐに、複数の Servlet で共通した部分に気がつくと思います。まずは開発を楽にする抽象クラスとして、 アプリケーション固有の Servlet をサブクラス化できる自分用の MainServlet を作るとよいでしょう。 サブクラスが必ずオーバーライドしなければならないメソッドは、 Servlet のテンプレートファイルの名前を返す getTemplateName() だけです。

サブクラスで、(ほとんどの Servlet で行なうように) データをコンテキストにセットする必要があるなら、loadData() メソッドを実装できます。

これでおしまいです。それ以外は MainServlet (と、当たり前ですが VelocityServlet) がやってくれます。

public abstract class MainServlet extends VelocityServlet {

  public Template handleRequest(HttpServletRequest request, HttpServletResponse response, Context ctx) {
    loadData( request, response, ctx );
    return getMyTemplate();
  }

  protected Properties loadConfiguration (ServletConfig config) throws IOException, FileNotFoundException  {
    String propsFile = config.getInitParameter(INIT_PROPS_KEY);
    Properties p = new Properties();

    if ( propsFile != null ) {
      InputStream iStream = getServletContext().getResourceAsStream( propsFile );

      if ( iStream != null ) {
        p.load( iStream );
      }
    }

    return p;
  }

  protected Template getMyTemplate( ) {
    Template template = null;
    try {
      template =  getTemplate( getTemplateName() + ".vm" );
    }
    catch (ParseErrorException pee) {
      mylog("Parse error for template " + pee);
    }
    catch (ResourceNotFoundException rnfe) {
      mylog("Template not found " + rnfe);
    }
    catch (Exception e) {
      mylog("Error " + e);
    }
    return template;
  }
  
  /** 
   * この Servlet で処理されるテンプレートファイル名を取得する。
   * 各サブクラスでオーバーライドされなければならない。
   */
  abstract protected String getTemplateName();

  /** 
   * データをコンテキストにロードする。
   */
  protected void loadData(HttpServletRequest request, HttpServletResponse response, Context ctx ) {
    ctx.put( "dummy", "dummy" );
  }
}

上で概略を説明したディレクトリをサポートする単純なビルドプロセスは、 以下のようなステップとなります。

1. ビルドプロセスで使うディレクトリのショートカットを定義する。
2. 出力先の (ビルド) ディレクトリに必要なファイルをコピーして、 ビルドを準備する
3. 全ての Java ファイルをコンパイルする。
4. 全てのテンプレートが入った JAR ファイルを作る。
5. (配布ディレクトリに) Web アプリケーションが入った WAR ファイルを作る。

上記の枠組みにしたがった具体例を以下に示します。

<project name="carImportAdmin" default="all" basedir=".">


  <!--	配備記述子(DD)、マニフェスト、プロパティなどのソースディレクトリ  -->
  <property name="dd" value="./dd"/>


  <!--  ビルドプロセスで使用するワークディレクトリ  -->	
  <property name="build" value="./staging"/>


  <!--  最終的なWAR ファイルのターゲットディレクトリ  -->
  <property name="dist" value="../build-ear/modules"/>


  <!--  全ての Java ファイルのソースディレクトリ  -->
  <property name="src" value="./src"/>


  <!--  テンプレートファイルのソースディレクトリ  -->
  <property name="templates" value="./templates"/>


  <!--  スタイルシートのソースディレクトリ  -->
  <property name="stylesheets" value="./stylesheets"/>


  <!--  コンパイルで使用するライブラリ  -->
  <property name="lib" value="${dist}/CarImport.jar;${dist}/FPGuiden.jar;${dist}/velocity-dep-1.2-rc3.jar"/>


  <target name="all" depends="init, compile, jar, war"/>

  <target name="init" depends="clean">
    <tstamp/>

    <mkdir dir="${build}"/>
    <mkdir dir="${build}/stylesheets"/>
    <mkdir dir="${build}/WEB-INF"/>
    <mkdir dir="${build}/WEB-INF/classes"/>
    <mkdir dir="${build}/WEB-INF/lib"/>

    <copy todir="${build}/WEB-INF">
      <fileset dir="${dd}">
        <include name="velocity.properties"/>
      </fileset>
      <fileset dir="${dd}/WEB-INF">
        <include name="web.xml"/>
      </fileset>
    </copy>
    <copy todir="${build}/WEB-INF/lib">
      <fileset dir="${dist}">
        <include name="velocity-dep-1.2-rc3.jar"/>
      </fileset>
    </copy>
    <copy todir="${build}/stylesheets">
      <fileset dir="${stylesheets}">

      </fileset>
    </copy>
  </target>


  <target name="compile">
    <javac srcdir="${src}" destdir="${build}/WEB-INF/classes" classpath="${CLASSPATH};${lib}">
    </javac>
  </target>

  <target name="jar">
    <jar jarfile="${build}/WEB-INF/lib/templates.jar"
      basedir="${templates}">
    </jar>
  </target>

  <target name="war" depends="init">
    <jar jarfile="${dist}/carImportAdmin.war"
      basedir="${build}">
    </jar>
  </target>

  <target name="clean">
    <delete dir="${build}"/>
  </target>

</project>