1. Assumptions
2. The Scope Of This Guide
3. Where To Put the Template Files
4. Setting the Configuration Properties
5. What about stylesheets?
6. Where to put the Velocity Jar
7. Making Life Easier for the Developer
8. A Build Process

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

This short guide can only be keept short because it assumes you already have a working knowledge af Velocity and how to use it in the J2EE environment, for example with Apache-Tomcat.

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

Deploying web-applications to Tomcat can be accomplished by a war-file, but at startup Tomcat explodes the war-file so the directory structure are available for the Velocity engine at runtime and the getRealPath() method in ServletContext returns the real path to the given directory.

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

Deploying the same war-file in WebLogic will not have the same effect, since WebLogic keeps its deployed war-files unexploded, and the getRealPath() method in ServletContext returns null. So how should you organize your properties file, templates, stylesheets, servlets and build process in this environment?

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

The scope of this little guide is to give you answers to these questions, so you can enjoy using Velocity even in the context of a commercial app server.

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

While all the relevant information can be found in the JavaDoc documentation, this quick guide will help you get started quickly.

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

Since the ClasspathResourceLoader can load a template from a resource found in the servlet engines classpath, it seems like a very good idea to jar all the template-files together and place this jar (template.jar for example) in WEB-INF/lib which will make it available as a resource in the classpath.

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

Although the properties file could be given any name, for this guide we will use velocity.properties since all documentation and examples on the Velocity site uses this filename.

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

This file should include the following two lines to configure the resource loader:

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

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

The file can contain other configurations as well.

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

Where to put velocity.properties velocity.properties はどこに置くか?

Put the velocity.properties file directly in the WEB-INF directory and include the following lines in your web.xml:

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>

and include the following implementation in your servlet(s):

そして、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;
  }

If you have any stylesheets you can place them anywhere you like, as long as you only make relative references to these files from your template files.

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

I prefer to have my stylesheets keept in a directory called stylesheets located under the root-directory of the web application (i.e. at the same level as the WEB-INF directory).

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

In your template files you can reference the stylesheets like this:

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

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

First of all you have to decide whether you will use the dependency-free version of velocity.jar or the version including all dependend jars. If you are not worried about collisions with Avalon Logkit, Commons Collections or Jakarta Oro, using the jar containing all dependencies is very convenient.

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

Putting the velocity jar in WEB-INF/lib your web application will result in it's classes being available in the classpath for that web application.

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

Using Velocity in 'real life' you quickly recognize a lot of similarity between your servlets. The first abstraction that will make life a little easier for the developers is a servlet like my MainServlet, which all application specific servlets can subclass. The only method the subclasses must override is the getTemplateName() method, which should return the name of this servlets template file.

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

If the subclasses needs to put data into context (which most servlets do) they can implement the loadData() method.

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

That's it. The rest is done by MainServlet (and VelocityServlet of course).

これでおしまいです。それ以外は 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;
  }
  
  /** 
   * Gets the name of the template file to be processed from this servlet. Should be 
   * overridden by every subclass. 
   * この Servlet で処理されるテンプレートファイル名を取得する。
   * 各サブクラスでオーバーライドされなければならない。
   */
  abstract protected String getTemplateName();

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

A simple build process that supports the outlined directory contains the follwing steps:

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

1. Define shortcuts for the directories used during the build process
2. Prepare the build by coping all necessary files to the staging (build) directory
3. Compile all java files
4. Make a jar containing all templates
5. Make a war containing the web application (in the distribution directory)

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

A concrete example following the above scheme:

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

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

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

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

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

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

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

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

  <!--  Libraries used in compile  --> 
  <!--  コンパイルで使用するライブラリ  -->
  <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>