Velocity JSP タグライブラリ The Velocity JSP Tag Library Geir Magnusson Jr. 熊坂祐二 高橋達男 新穂洋史 veltag
  1. So You Have To Use JSP...
  2. Using The Velocity Taglib
  3. Building The Velocity Taglib
  4. Configuration
  1. JSPを使わなくてはならないなら・・・
  2. Velocity タグライブラリを使う
  3. Velocity タグライブラリのビルド
  4. 設定

Sometimes it appears you don't have a choice - technology decisions are made based on all sorts of factors, ranging from network externalities ("They're using it - I should too...") to legacy considerations ("They used it - I have to...").

時には、選択できないこともあります。技術の決定は、 とても多くの要因に基づいて行われ、その要因は、ネットワークにもとづく外部的なもの (「彼らが使っているから・・・」)から 過去の資産への配慮 (「彼らが使ったから・・・」)まで様々です。

In the event where the usage of JSP is mandatory, we offer a JSP tag library that lets you take advantage of the simple control directives and powerful binding to the Java object model offered by Velocity. Using Velocity in your JSPs is as simple as :

JSP を使用せざるを得ない人のために、シンプルな制御指示子や Java オブジェクトモデルとの強力な結びつきといった Velocity の利点を生かせる JSP タグライブラリを提供しています。 JSP で Velocity を使うのはこんなに簡単です。

Velocity! #set($mybean = $scopetool.getPageScope("mybean")) #if(true) this is true! #end
$mybean.string
#foreach($item in $mybean.array) $item
#end ]]>

Not hard at all, is it?

すごく簡単でしょ?

What Are The Advantages? 利点は何?

The first question asked when confronted with this subject is something along the lines of "What advantage does this have over 'pure' Velocity?". Generally, there are few reasons why one would take a Velocity-only system, and convert it to a JSP system with Velocity embedded in the JSP pages. The only reason that you might want to do this is to use an existing JSP taglib that you want to use that you don't have the source code for, or don't wish to dig out the core functional classes of a taglib you do have the source for. Otherwise, you could just drop those core classes in the Context, and access them directly from within the Velocity template.

この話題にとりくむ際に最初に聞かれる質問は、「「純粋な」Velocity と比べて、 どんな利点があるのか？」といったものです。 一般に、Velocity のみのシステムから、JSP ページに Velocity を埋め込んだ JSP システムに移行しなければならない理由はほとんどありません。 もしそうしたいと思うのなら、その唯一の理由は、 既存の JSP タグライブラリを使いたいのにソースコードがないからか、 ソースはあるがタグライブラリのコア機能のクラスに手を入れたくないからでしょう。 そうでないなら、こうしたコアのクラスをコンテキストに入れて、 Velocity テンプレート内で直接アクセスすれば済むからです。

The advantages, then, are found in a JSP-centric environment, where an existing application is already written in JSP and you wish to add or maintain functionality. Some things that Velocity provides :

したがって、このアプローチが役に立つのは、JSP が中心的な環境で、 既存のアプリケーションが JSP で書かれていて、機能を追加・変更したい場合です。 Velocity は以下のような機能を提供します。

  • Simple access to Java objects, without any need to create a taglib shell. If it has public methods on a public interface, you can drop it right into a scope and access directly (or use a tool to create an instances of the class for you.)
  • Simple access to complicated Java objects. It's not clear how to access an arbitrary call chain such as $foo.bar( $thing ).getIterator().hasNext() in JSP.
  • Although this is a matter of personal taste, some people prefer the control directives of Velocity ( #if(), #else(), #elseif(), #foreach() ) to the various taglibs that offer the same functionality. De gustibus non est disputandum!.
  • An easy bridge between complicated Java objects and JSP - for example if you wished to dynamically choose/create an object at runtime, and then poke into a scope for access in other parts of the JSP, you could do that. 
             <vel:velocity strictaccess="true">
             #set($reqbean = $scopetool.getRequestScope("beaninrequest"))
             #set($newthing = $reqbean.getThing().makeBlue("azure"))
             $request.getSession().setAttribute("bluething", $newthing)
         </vel:velocity>
    Or something like that :)
  • If nothing else, there are always the Velocimacros.
  • タグライブラリのシェルを作成しなくても、Java オブジェクトに簡単にアクセスできます。 public インタフェースに public メソッドがあれば、それをスコープにそのまま入れて、 直接アクセスできます（あるいは、自分のクラスのインスタンスを生成するツールも使えます)。
  • 複雑な Java オブジェクトに簡単にアクセスできます。 JSP では $foo.bar( $thing ).getIterator().hasNext() といった、 任意の呼び出し連鎖には簡単にアクセスできません。
  • 好みの問題ですが、Velocity の制御指示子 (#if()、#else()、#elseif()、#foreach()) を、 同じ機能のタグライブラリよりも好む人もいます。古代ローマの諺にあるように、 「人の好みについては議論すべきではありません (De gustibus non est disputandum)」。
  • 複雑な Java オブジェクトから JSP への橋渡しが簡単です -- たとえば、 実行時にオブジェクトを動的に選択/作成して JSP の他の部分でアクセスできるようにスコープにつっこみたい場合は、こんな風にできます。 
             <vel:velocity strictaccess="true">
             #set($reqbean = $scopetool.getRequestScope("beaninrequest"))
             #set($newthing = $reqbean.getThing().makeBlue("azure"))
             $request.getSession().setAttribute("bluething", $newthing)
         </vel:velocity>
    まあこんな感じです :)
  • 何がなくとも、Velocimacro があります。

The biggest challenge in bringing together Velocity and JSP is the 'impedance matching' related to scope and bean access. 'Scope', the fundamental storage mechanism in JSP, is a concept that comes from the underlying servlet API, where data objects are stored for later retrieval within the page, request, session or application. Velocity organizes data in a non-hierachical mechanism called the 'context', the expectation being that a controller servlet or other non-view code will manage and organize the data accessable to the template.

Velocity と JSP をまとめる際の最大の問題は、 スコープとBeanアクセスに関する「インピーダンスマッチング」です。 JSP での基本的なデータ格納メカニズムである「スコープ」は、ベースにある Servlet API から派生した考え方で、データオブジェクトが、 ページ／リクエスト／セッション／アプリケーション内で保存・取得されます。 Velocity は「コンテキスト」と呼ばれる非階層的な仕組みでデータを管理しており、 テンプレートでアクセス可能なデータの管理は、コントローラである Servlet など、ビュー以外のコードが行うことを前提としています。

So to make data access in JSPs easy using the Velocity taglib, two separate approaches are offered. These two approaches, automatic access and strict access, allow two distinct ways of managing and accessing data. These two ways can also be used together.

したがって、Velocity タグライブラリを使って JSP 内で簡単にデータアクセスするために、 2種類の方法が提供されています。自動アクセスと厳密アクセスという2種類の方法で、 2通りの異なるやり方でのデータの管理やアクセスが可能となっています。 併用も可能です。

Automatic Scope Access 自動スコープアクセス

The first way, automatic access, is the most convenient. When an object is referenced (via a VTL 'reference'), the scopes are searched to find an object with the same id. The scopes are searched in the order of :

1つ目のやり方である、自動アクセスの方が便利です。 (VTL「リファレンス」を通して) オブジェクトが参照される場合、 同じ ID のオブジェクトを見つけるためにスコープが検索されます。 スコープは以下の順序で検索されます

  1. page scope
  2. request scope
  3. session scope
  4. application scope
  1. ページスコープ
  2. リクエストスコープ
  3. セッションスコープ
  4. アプリケーションスコープ

Automatic scope access is enabled by default. To use automatic scope access, just access the bean by name. For example :

自動スコープアクセスは、デフォルトで使えます。 自動スコープアクセスを使うには、名前で Bean にアクセスするだけです。 例えば、

#foreach($item in $mybean.array) $item
#end ]]> #foreach($item in $mybean.array) $item
#end ]]>

While automatic scope access is the easier of the two methods, integrating with existing applications might require using the other access mode, strict scope access, or a combination of the two.

自動スコープアクセスの方が簡単ですが、既存のアプリケーションと統合するためには、 もう一つのアクセスモードである厳密スコープアクセスを使うか、 あるいは両者を組み合わせて使う必要があるかもしれません。

Strict Scope Access 厳密スコープアクセス

The alternative (or addition to) Automatic Scope Access is something called Strict Scope Access. Strict Scope Acccess means that the Velocity Context won't search the scopes for you - you must retrieve objects directly using ScopeTool that is provided for your use in the template. This is a closer model to that of regular JSP, where the designer must be aware of the scopes that objects are stored in.

自動スコープアクセスの代替手段（または追加手段）が、厳密スコープアクセスと呼ばれているものです。 厳密スコープアクセスとはどういうことかというと、Velocity コンテキストがスコープを検索してくれない -- テンプレートで使用するために用意されている ScopeTool を使って、 直接オブジェクトを取り出さなければならない -- ということです。 これは通常の JSP により近いモデルで、 デザイナはオブジェクトがどのスコープに保存されているかを把握しなければなりません。

For example, the following snippet of JSP shows how the scopetool is used to access an object in the request scope, and add it to the Velocity context. Note how the strictaccess property is set to true in the <vel:velocity strictaccess="true"> tag. This tells the Veltag taglib to not do any automatic scope searching. Note that you can mix the two modes, leaving off (or setting to false) strictaccess and also using the scopetool to eliminate any question about the source of an object.

例えば、以下の JSP のコードでは、ScopeTool を使ってリクエストスコープ内のオブジェクトにアクセスし、 オブジェクトを Velocity コンテキストに追加する方法を示しています。 <vel:velocity strictaccess="true"> タグで、 strictaccess プロパティが true に設定されているのに注目してください。 こうすれば Veltag タグライブラリが自動スコープ検索を行わないようになります。 注意：strictaccess をオフのままにしておき(または false に設定し)、 その上でどこからのオブジェクトかを気にしないですむように ScopeTool を使うことで、 2つのモードの混在も可能です。

#set($reqbean = $scopetool.getRequestScope("beaninrequest")) $reqbean.string
#foreach($item in $reqbean.array) $item
#end ]]>

Again, pretty straightforward.

こちらも、かなり簡単です。

To use the Velocity taglib, you need to build it, as it is not yet included in the main Velocity jar. In the Jakarta tradition, we made it very easy to build. The code for the project is located in the contrib section of the distribution under /contrib/temporary/veltag. It is under the temporary directory as it is hoped this package will be accepted by the Jakarta Taglibs project.

Velocity タグライブラリを使う場合、メインの Velocity の JAR ファイルにはまだ含まれていないので、ビルドする必要があります。 Jakarta での伝統に従い、ビルドを非常に簡単にしました。 このプロジェクトのコードは、配布の contrib セクションの /contrib/temporary/veltag の下 [ http://cvs.apache.org/viewcvs/jakarta-velocity/contrib/temporary/veltag/] に置いてあります。一時的なディレクトリの下にあるのは、このパッケージは Jakarta Taglibs プロジェクトに受け入れられることを希望しているからです。

The Easy, JJAR Way JJARを使う簡単な方法

The Veltag taglib can be built using a new, experimental jar management tool called JJAR (Jakarta Jar Archive & Repository) which makes finding and retrieving the dependencies to build the taglib simple.

Veltag タグライブラリは、新しい実験的な Jar ファイル管理ツールである JJAR (Jakarta Jar Archive & Repository) を使ってビルドできます。このツールは、タグライブラリを簡単にビルドできるように、 依存するライブラリを見つけて取り出してくれます。

Please note that JJAR is currently a work in progress - while every effort will be made to ensure that the JJAR-based build works, it may not always be so. In that case, do it the regular way, listed below.

注意：JJAR は現在開発中です -- JJAR ベースのビルドが動作するように、 あらゆる努力をしていますが、動作しない可能性もあります。 その場合には、後で示す一般的な方法で行ってください。

To build with JJAR :

JJAR でビルドする手順は以下の通りです。

  1. Ant, the fabulous Jakarta build tool, must be installed.
  2. Get the Velocity distribution from CVS or a nightly snapshot.
  3. Change directory to the /contrib/temporary/veltag directory in the Velocity distribution.
  4. Type : 
          $ ant getjars
    This will fetch JJAR and then use JJAR to fetch the dependencies du jour for Veltag.
  5. Type : 
          $ant jar
    which will build the veltag-XX.jar (XX = current version).
  1. すぐれたビルドツールである、Ant がインストールされていなければなりません。
  2. CVS または夜間スナップショットから Velocity 配布を取得します。
  3. Velocity 配布の /contrib/temporary/veltag ディレクトリへ移動します。
  4. 以下のようにタイプします。 
          $ ant getjars
    こうすれば、JJAR を取得し、そのJJAR を使って、 本日の Veltag の依存ライブラリを取得できます。
  5. 以下のようにタイプします。 
          $ant jar
    これで、veltag-XX.jar（XX = 現在のバージョン）がビルドされます。

That's it. Pretty easy.

以上です。かなり簡単です。

The JJAR-Is-A-Work-In-Progress Way JJARが不安な人のための方法

In the event the JJAR-based build is broken, or you just enjoy schlepping around finding jars, do the following to build Veltag.

JJAR ベースでのビルドがうまくいかなかった場合や、 JAR ファイルを探して回るのが好きな人は、 以下の手順で Veltag をビルドして下さい。

To build, you need the following :

ビルドで必要な手順は以下の通りです。

  • Ant, the fabulous Jakarta build tool, must be installed.
  • You will need a servlet API jar. We recommend you get it from here for servlet 2.2 and here for the unreleased servlet 2.3 API. Note - if you are a JSP user, you will have one included with your servlet engine.
  • A velocity.jar. This can be found, of course, here.
  • The build script expects to find the servlet and velocity jars in the /contrib/temporary/veltag/lib/ directory. Modification of the build script is easy if they are in another location. Look for 'servlet.home' and 'velocity.home' in the /contrib/temporary/veltag/build.xml file.
  • Once the above is complete, cd into /contrib/temporary/veltag in the Velocity distribution and type 'ant'. The jar should build for you.

Using the taglib is very straightforward. The following assumes that you have setup a servlet container with JSP support, such as Tomcat, and know enough to write and view a simple JSP page. Also, all directory references are relative to the root of the veltag project, not the Velocity distribution.

このタグライブラリを使うのは非常に簡単です。以下の説明は、 Tomcat のような JSP をサポートする Servlet コンテナをセットアップしており、 簡単な JSP ページを書いて表示させられるだけの知識があることを 前提としています。また、すべてのディレクトリ参照は、Velocity 配布ではなく、 veltag プロジェクトのルートの相対パスです。

To test the Velocity Taglib :

Velocity Taglib をテストするには

You need to copy the veltag-XX.jar to the WEB-INF/lib directory of your webapp. (Where XX is the current version number.
veltag-XX.jar を Web アプリケーションの WEB-INF/libディレクトリにコピーしてください。 (XXは、現在のバージョン番号です)
Take the example taglib descriptor, /examples/veltag.tld and place in WEB-INF of your webapp.
タグライブラリ記述子のサンプルである/examples/veltag.tld を あなたのWebアプリケーションの WEB-INF ディレクトリにコピーしてください。
Finally, add 
    <taglib>
      <taglib-uri>http://jakarta.apache.org/taglibs/veltag-1.0</taglib-uri>
      <taglib-location>/WEB-INF/veltag.tld</taglib-location>
    </taglib>
to your web.xml file, within the <webapp> section.
最後に、以下の内容を web.xml ファイル内の <webapp> セクションに追加してください。 
     <taglib>
       <taglib-uri>http://jakarta.apache.org/taglibs/veltag-1.0</taglib-uri>
       <taglib-location>/WEB-INF/veltag.tld</taglib-location>
     </taglib>

If you wish to use the included example JSP, you will also need to compile examples/SimpleBean.java and place the resulting SimpleBean.class into the WEB-INF/classes directory in your webapp.

JSP サンプルを使いたい場合は、上記に加えて、 examples/SimpleBean.java をコンパイルし、 生成される SimpleBean.class を Web アプリケーションの WEB-INF/classes ディレクトリ内に置く必要があります。

After that, try the example JSP found in examples/. Drop it into the root of your webapp and view it with your browser. Enjoy!

その上で、examples/ にある JSP のサンプルを試してください。 この JSP を Web アプリケーションのルートにコピーし、ブラウザで見ます。 楽しんでみてください。

Please direct all comments, questions, fixes and contributions to Geir Magnusson Jr. or the Velocity user list. To subscribe to the Velocity lists, read this and follow the instructions at the end.

コメントや質問、修正や貢献については、 Geir Magnusson Jr. または Velocity ユーザ メーリングリストに連絡してください。 Velocity メーリングリストに参加するには、 このページ を読み、ページの指示に最後まで従ってください。

Please note that this code is not an official part of the Velocity distribution.

注意: このコードは、公式の Velocity 配布の一部ではありません。 [訳注：つまり、通常ダウンロードする .zip ファイルや .tar.gz ファイルには含まれていません。上にも書いたとおり、コードはhttp://cvs.apache.org/viewcvs/jakarta-velocity/contrib/temporary/veltag/ にあります。]