VelocityStruts - ユーザガイド

VelocityStruts

その他のサブプロジェクト

このガイドでは、Struts ベースの Web アプリケーションのビューのレンダリングを行う VelocityViewServlet のセットアップと設定の方法について説明します。このサーブレットは Struts のコントローラにより提供される情報を元に、 *.vm (Velocity テンプレート) ファイルをレンダリングする VelocityEngine を作成します。

いくつかのビルトインツールが作成されました。これらはTiles、Validator、フォーム、リンク、メッセージ、エラーのためのStruts JSPタグライブラリと同じ機能を提供します。

配布物には Struts ツールの使用例が含まれています。この例は Web アーカイブファイル (velstruts.war) にパッケージングされています。

このドキュメントは Velocity テンプレート言語やその文法を紹介するものではありません。もし Velocity を触るのが初めてならば、 Velocity を使い始めるを参照しておいてください。

背景
Model 2 アーキテクチャ
インストール
ビューの表示
1. Velocity テンプレート言語
2. データを渡す
3. サーブレットリソースへのアクセス
4. Strutsフレームワークリソースへのアクセス
5. ビューツール(訳注: このリンク先は存在しません。最新のドキュメントではこのリンクは削除されています。)

背景

このドキュメントは Velocity を Struts アプリケーションと統合するのに必要なステップを説明します。読者はすでにこれらのプロジェクトの基本的な部分を理解していることを前提とします。

Velocity と Struts を始める前に、ユーザガイドを読み、アプリケーション例とリファレンスガイドをインストールして眺め、それから VelocityStruts をあなたのアプリケーションのビューレイヤとして使用することをお勧めします。

もしこのドキュメントがあなたの疑問を解決しきれないと判断したら、質問を Velocity-User メーリングリストにポストしてください。喜んで手助けします! (そしてドキュメントを改良していきます!)

Model 2 アーキテクチャ

JSP の世界では、 Model 1 アーキテクチャと Model 2 アーキテクチャが Web アプリケーションの設計、製造の方法として確立されました。この2つの設計アプローチの基本的な違いを理解することは重要です。 JSP は Model 2 アーキテクチャだけではなく、 Model 1 アーキテクチャとして設計された Web アプリケーションでも使用することができます。 Velocity は違います。 Velocity は Model 2 に基づく Web アプリケーションアーキテクチャのビューテクノロジとして設計されました。

Model 1 アーキテクチャ

Model 1 アーキテクチャでは、単体の JSP ページで、リクエストを処理しクライアントにレスポンスを返します。 MVC でいうところの、コントローラおよびビューが、同じJSPページ内に実装されています。 Model 1 アーキテクチャは非常に単純なアプリケーションのシナリオのみに適します。中規模から大規模のプロジェクトでは、ビジネスロジックとビューの間の分離がきちんとできていないことが、サーバ開発者の仕事から Web デザイナの仕事を分ける際の困難さに結びつき、プロジェクト管理の頭痛の種となります。

Model 2 アーキテクチャ

Model 2 アーキテクチャでは、ビジネスロジック、データアクセス、リクエストハンドリングを含むコントロールコンポーネントはビューコンポーネントから明確に分離されます。ビューはいかなる処理ロジックも含みません。リクエストの処理結果であるデータの表示を行うだけです。これは静的なページであることもありますが、大抵は動的なページとなるでしょう。このようなアプローチは一般的に、開発者および Web デザイナの役割や責任の明瞭な線引きを促します。アプリケーションがより複雑であるほど、 Model 2 アーキテクチャを使用する利点はより大きいものとなるでしょう。

JavaServer Pages Model 2 アーキテクチャを理解するで Model 1 と Model 2 アーキテクチャのより深い議論が提供されています。

これは何を意味するの?

Struts フレームワークは両方のアーキテクチャをサポートしていますが、実際には提供される機能はすべて Model 2 アプリケーションの構築を容易にすることが目的です。 Velocity はそうではなく、Model 1 アーキテクチャでは使用することができません。そのような設計を支援するライブラリがないのです。あなたが Velocity をプロジェクトに採用することを決定する前に、このような事実をすべて把握していることを確認するため、ここで強調しておきます。これは、 Model 1 アプローチあるいは Model 1 / Model 2 混合アプローチ上で構築された既存のアプリケーションを移植することを検討している人々には特に重要です。最後に、良いお知らせです。現在の本格的なアプリケーションでは Model 2 は最先端技術であり、この手法を用いる限り、 Velocity はあなたの力強い味方となるでしょう。

インストール

この章では Struts Web アプリケーションのビューの表示を行えるように、 VelocityViewServlet を設定する基本的なセットアップ方法を説明します。

セットアップの手順は普通の VelocityViewServlet のインストールとだいたい一緒です。より詳細については見直しておいてください。拡張したものである VelocityLayoutServlet や、他のカスタム実装も Struts で使用することができます。 (このサーブレットは、 html レイアウトを複数のページで共有し、再利用する機能が加えられています。)

ステップバイステップ:

velocity-tools-x.x.jar は VelocityStruts と VelocityView のクラス群を含んでいるものであり、 WEB-INF/lib に配置します。
*.vm ファイルへのリクエストを処理する VelocityViewServlet を、サーブレットコンテナにインストールする (web.xml への記述) 必要があります。
設定ファイル velocity.properties を追加する必要があります。
toolbox.xml ファイルを追加し、 Struts オブジェクトをテンプレートから利用できるようにするための、標準ツールのマッピングをセットアップします。 (toolbox.xml ファイルのサンプルが下にあります。)

これで全部です!

ここまで終われば、 Struts ActionMapping の 'forward' を Web アプリケーションのルートディレクトリに配置されている *.vm ファイルへ変更するすることで、それを表示することが可能となっているはずです!

toolbox.xml


<?xml version="1.0"?>

<toolbox>
  <tool>
     <key>link</key>
     <scope>request</scope>
     <class>org.apache.velocity.tools.struts.StrutsLinkTool</class>
  </tool>
  <tool>
     <key>msg</key>
     <scope>request</scope>
     <class>org.apache.velocity.tools.struts.MessageTool</class>
  </tool>
  <tool>
     <key>errors</key>
     <scope>request</scope>
     <class>org.apache.velocity.tools.struts.ErrorsTool</class>
  </tool>
  <tool>
     <key>form</key>
     <scope>request</scope>
     <class>org.apache.velocity.tools.struts.FormTool</class>
  </tool>
  <tool>
     <key>tiles</key>
     <scope>request</scope>
     <class>org.apache.velocity.tools.struts.TilesTool</class>
  </tool>
  <tool>
     <key>validator</key>
     <scope>request</scope>
     <class>org.apache.velocity.tools.struts.ValidatorTool</class>
  </tool>
</toolbox>

ビューの表示

この章では、 Struts アプリケーションで Velocity を利用してビューを表示させる際の概念の手ほどきを行います。

Velocity テンプレート言語

Velocity は Java で実装されたテンプレートエンジンです。 Velocity テンプレートは、主に埋め込みスクリプト入りの HTML ページです (Velocity は他の多くのアプリケーションシナリオのために使用されてもいますが)。スクリプトは Velocity テンプレート言語 (VTL) で記述されます。下記は VTL ステートメントを埋め込んだ HTML のシンプルな例です:


<HTML>
<BODY>
    <h2>注文の確認</h2>

    <h3>送付先住所:</h3><br>
    名前: $customer.name<br>
    番地: $customer.street<br>
    市: $customer.zip $customer.city

    <h3>注文の品</h3><br>
    <table>
    #foreach( $item in $order.items )
        <tr>
            <td>$item.quantity</td>
            <td>$item.description</td>
        </tr>
    #end
    </table>
</body>
</html>

処理後、下記のような出力となります。


<HTML>
<BODY>
    <h2>注文の確認</h2>

    <h3>送付先住所:</h3><br>
    名前: Peter Pan<br>
    番地: Crain St. 10<br>
    市: 60201 Evanston IL

    <h3>注文の品</h3><br>
    <table>
        <tr>
            <td>1</td>
            <td>Hair Dryer, Philips, 1000W, white</td>
        </tr>
        <tr>
            <td>1</td>
            <td>Kitchen Mixer, Betty Bossy, 240W, black</td>
        </tr>
    </table>
</body>
</html>

VTL はビューデザイナを意識したシンプルなテンプレートスクリプト言語として、最初から最後まで設計されました。サポートされている指示子は10未満であり、習得することが容易です。実際、ほとんどの人々は1日以内に習得して生産的になっています。

Velocity は Java のスクリプトレットを許容せず、明確な MVC の線引きを行います。

VTL の適用範囲の詳細については次の2つのドキュメントを調べてください:

データを渡す

Web アプリケーションにおいての Velocity の主要な目的は、動的なビューを生成するため、 HTML テンプレートと動的なアプリケーションデータをマージすることです。 Velocity の最も重要な点は、アプリケーションの (MVCでいうところの) コントローラが、アプリケーションデータをテンプレートへ渡すことを可能にするメカニズムなのです。

Struts ベースのアプリケーションと Velocity テンプレートサーブレットの関係を理解することが重要です。両方とも、特定の処理を行うシンプルな Java サーブレットです。

Struts アプリケーションへのリクエストが処理され、アプリケーションデータが処理され、最終的には全てのデータと制御はビューレイヤにフォワードされます。

このケースでは、 Velocity サーブレットは HTML 出力のために、渡されたアプリケーションとテンプレートをマージする役割を持ちます。

Velocity サーブレットは Struts アプリケーションのみと関係しているわけではないことを覚えておいてください。 Web クライアントからの直接のリクエストを受け付けることができますし、他のどんなサーブレットアプリケーションとも同様にできます。技術的なことを言うと、 Struts はリクエストを javax.servlet.RequestDispatcher の forward メソッドを用いて Velocity へ渡します。

アプリケーションデータは、サーブレットリクエスト、サーブレットセッション、サーブレットコンテキストのいずれかの属性として Struts サーブレットから Velocity サーブレットへ渡されます。

したがって、開発者はビューレイヤにデータを渡すために属性を設定し、そのデータをテンプレートから利用できるようにする必要があります。例:

request.setAttribute("Customer", CustomerObj); CustomerObj インスタンスの持つ全ての public メソッドがテンプレートデザイナへ提供され、利用することができます。 public の getName() メソッドがあると仮定した場合、このように書くことができます: $Customer.name または $Customer.getName() 。

テンプレートデザイナへ渡されるオブジェクトには優先順位があります。例えば、セッションとリクエスト両方に "foo" という属性があった場合、

request.setAttribute("foo", "request foo");
session.setAttribute("foo", "session foo");

リクエストの属性が優先され、テンプレート内で

$foo

を使用しますと次が得られます。

request foo

優先順位は以下の順番で与えられます:

toolbox.xml にて指定されたツール(e.g. $link, $tiles, etc.)
サーブレットのクラス (e.g. $request, $response, $session, $application)
テンプレート内でローカルにセットされたリファレンス
リクエストの属性
セッションの属性
サーブレットコンテキスト (application) の属性

この優先順位によって開発者はテンプレートデザイナから重要なリファレンス (ツールやサーブレットリソース) の制御を確保できます。また、JSP と Struts で開発するのと同じように、サーブレットのさまざまなスコープに値をセットできるようになります。

サーブレットリソースへのアクセス

VelocityStruts は、各テンプレート処理リクエストごとに、自動的に Servlet API の以下のオブジェクトをコンテキストを設定します:

コンテキストキー	クラス	備考
$request	javax.servlet.http.HttpServletRequest	処理中のサーブレットリクエスト
$session	javax.servlet.http.HttpSession	もし存在する場合、処理中のセッション
$application	javax.servlet.ServletContext	サーブレットコンテキスト
$response	javax.servlet.http.HttpServletResponse	処理中のサーブレットレスポンス

以下の例では、サーブレットのリソースが Velocity テンプレートからどのようにアクセスされるかを示します。この例は、処理中のサーブレットリクエストの HTTP ヘッダーのフィールドのリストを表示します。同じ方法で、上記にリストされているオブジェクトのどんな public メソッドでもテンプレートの内部から呼ぶことができます:

#foreach( $header in $request.HeaderNames )
  <b>$header:</b> $request.getHeader($header)<br>
#end

出力結果はこのようになります:

Referer: http://localhost:8080/struts/doc/examples.html
Connection: Keep-Alive
User-Agent: Mozilla/4.79 [en] (Windows NT 5.0; U)
Pragma: no-cache
Host: localhost:8080
Accept: image/gif, image/jpeg, image/pjpeg, image/png, */*
Accept-Encoding: gzip
Accept-Language: en
Accept-Charset: iso-8859-1,*,utf-8
Cookie: JSESSIONID=aaaecXd7bnLPAr

Strutsフレームワークリソースへのアクセス

Struts フレームワークは、テンプレートデザイナにとって役立つリソースを提供します。これらは、物理的なリソースの論理名、国際化されたメッセージ、エラーハンドリング、フォームハンドリングなどを含んでいます。気になるところとしては、テンプレートデザイナがどのようにフレームワークのリソースへアクセスすることができるかでしょう。 JSP では、一連のカスタムタグライブラリが、テンプレートデザイナに Struts フレームワークのリソースへのアクセスを提供します。 Velocity では、 JSP カスタムタグライブラリと等価なものとして ビューツールがあります。ビューツールは非常にシンプルなものです。それらは Velocity コンテキストの中に格納される、 public メソッドを持つ Java オブジェクトです。ツールはキーによってアクセスされ、テンプレートデザイナはそれらの public メソッドを呼び出すことができます。

テンプレートデザイナーに Struts フレームワークのリソースへのアクセスを提供する 7つのビューツールが VelocityStruts には含まれています。これらの7つのビューツールは、 Struts と Velocity 間の統合を実現する、このプロジェクトのコアとなる部分です。

コンテキストキー	クラス	備考
$text	MessageTool	国際化されたテキストのための Struts のアプリケーションリソースへのアクセスを提供します。
$errors	ErrorsTool	Struts のエラーメッセージをチェックし、出力するためのメソッドを提供します。
$messages	ActionMessagesTool	Struts のアクションメッセージに関するメソッドを提供します。
$link	StrutsLinkTool	URIに関するメソッドを提供します。
$form	FormTool	フォームや、Struts アプリケーションのコンテキスト内のフォームビーンに関するさまざまなメソッドを提供します。
$tiles	TilesTool	Struts アプリケーションのコンテキスト内でTiles に関するさまざまなメソッドを提供します。
$validator	ValidatorTool	Struts アプリケーションのコンテキスト内で動的にjavascript によるバリデーションを生成するメソッドを提供します。
注意: ここにあるキーは推奨されている値です。設定で変更することができます。

以下の例は、国際化メッセージに関する処理を行う MessageTool のいくつかの機能を示しています。例では、 Struts のメッセージリソースに以下の key=value のペアを含んでいると仮定します:


title=Struts Example Application
test=This string has 4 replacement parameters: {1}, {2}, {3}, {4}

以下のスクリプト...


$text.get("title")
$text.get("test", ["bear", "dog", "cat"])
$text.exists("tutle")
$text.getLocale()

..はこの出力を生成します:


Struts Example Application
This string has 4 replacement parameters: bear, dog, cat, {4}
false
en

ビューツールに関する詳細は、ツールリファレンスドキュメントを参照してください。また、 Velocity/Struts サンプルアプリケーションには、これらのツールがどのように使用されるかを示す、いくつかの例が付属しています。

[訳注: この文書は Shinobu Kawai 野瀬直樹が翻訳しました。日本語訳に対するコメントがあれば、report@jajakarta.orgに送って下さい。]