Velocity - VelocityView

VelocityView

VelocityView Tools

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

概要

VelocityView provides support for rapidly and cleanly building web applications using Velocity templates as the view layer. The project is designed with the Pull-MVC Model in mind and works well in conjunction with web application frameworks that act as the controller (e.g. Struts), but can be used quite effectively on its own for those creating simpler applications.

VelocityView は Velocity テンプレートをビューレイヤとして使用する Web アプリケーションを迅速かつ簡潔に構築するためのサポートを提供します。このプロジェクトは Pull-MVC Model を念頭において設計され、コントローラとして振舞う Web アプリケーションフレームワーク (例: Struts) と連携して動作します。また、単独でも動作しますので、シンプルなアプリケーションの作成にも使うことができます。

Key features:

主な機能:

VelocityViewServlet class - standalone servlet that renders Velocity templates. Invoked directly from web clients requests, or via servlet forwarding similar to how JSP files are rendered by JSPServlet.
The HttpServletRequest, HttpSession, ServletContext, and their attributes are automatically available in your templates.
Tools can also be made available to your templates, through a toolbox configuration file.
A number of useful, extendable tools for developing web applications are already provided for your convenience.
Logging can be directed to the log infrastructure of the Web application. (default is the logging facility provided by the Servlet API).

VelocityViewServlet クラス - Velocity テンプレートをレンダリングするスタンドアロンのサーブレットです。これは Web クライアントからの直接リクエストがあったとき、または他のサーブレットからフォワードされたときに、 JSP ファイルが JSPServlet によってレンダリングされるのと同じように起動されます。
HttpServletRequest、HttpSession、ServletContext とそれらの属性は自動的にテンプレートから利用可能となります。
ツールも toolbox 設定ファイルにより、テンプレートから利用可能です。
Web アプリケーションの開発に役立つ拡張可能なツールがいくつか提供されています。
Web アプリケーションのログ基盤へロギングすることができます。 (デフォルトはサーブレット API で提供されているロギング機構)。

Using VelocityViewServlet, it becomes possible to write web applications that are independent of a particular view technology. This opens a straightforward migration path between JSP pages and Velocity templates as the view layer technology in web applications.

VelocityViewServlet を使用することで、特定のビューテクノロジに依存しない Web アプリケーションを作成することが可能になります。 Web アプリケーションでのビューレイヤテクノロジとして JSP ページ、 Velocity テンプレート間のストレートな移行を可能にします。

A typical application use-case is to provide the view rendering layer for a servlet-based web application framework. The VelocityStruts subproject uses the approach to bring Velocity templates to the Struts application framework.

一般的なアプリケーションの適用ケースとしては、サーブレットベースの Web アプリケーションフレームワークの、ビュー表示のためのレイヤを提供することです。 VelocityStruts サブプロジェクトは Velocity テンプレートを Struts アプリケーションフレームワーク上で利用するアプローチを使用しています

インストール

The VelocityViewServlet needs to be installed into your servlet container so it can handle all request for *.vm (velocity template) files. There are only two additional configuration files necessary, and they are shown in detail below.

*.vm (Velocity テンプレート) ファイルのリクエストをすべて拾うように、 VelocityViewServlet をサーブレットコンテナへインストールする必要があります。追加しなければならない設定ファイルは2つだけです。詳細は以下を参照してください。

サーブレットのセットアップ

The servlet configuration (web.xml) must be modified to include a reference to the special Velocity-based servlet which will perform the rendering. All *.vm files are mapped to this servlet which will populate the 'context' with Request, Session, and Application scopes plus additional tools specified in the toolbox.xml file. The servlet will use this contextual information and the Velocity Engine to render the template file.

サーブレットの設定 (web.xml) には、表示処理を実行する Velocity ベースのサーブレットへの参照を含めるよう変更しなければなりません。全ての *.vm ファイルはこのサーブレットへマッピングされます。このサーブレットにより、Request, Session, Application スコープ、さらに toolbox.xml ファイルで指定されているツール群が 'context' へ設定されます。このサーブレットはテンプレートを表示するためにこのコンテキストのデータと、 Velocity エンジンを使用します。

Note: Additional functionality can be achieved through subclassing this servlet, and will be discussed further in the VelocityLayoutServlet below.

注: 機能追加はこのサーブレットをサブクラス化することで実現でき、このことについては VelocityLayoutServlet でさらに言及します。

web.xml

<!-- Define Velocity template compiler -->
<servlet>
  <servlet-name>velocity</servlet-name>
  <servlet-class>
    org.apache.velocity.tools.view.servlet.VelocityViewServlet
  </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>

<!-- Map *.vm files to Velocity -->
<servlet-mapping>
  <servlet-name>velocity</servlet-name>
  <url-pattern>*.vm</url-pattern>
</servlet-mapping>

<!-- Velocity テンプレートコンパイラを定義 -->
<servlet>
  <servlet-name>velocity</servlet-name>
  <servlet-class>
    org.apache.velocity.tools.view.servlet.VelocityViewServlet
  </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>

<!-- *.vm ファイルを Velocity にマッピングする -->
<servlet-mapping>
  <servlet-name>velocity</servlet-name>
  <url-pattern>*.vm</url-pattern>
</servlet-mapping>

Velocityの設定

Velocity configuration is optional, and for most applications the defaults will work fine. The velocity.properties file contains settings that affect logging, encoding, and macro settings.

Velocity の設定は任意であり、多くのアプリケーションではデフォルト設定で動作します。 velocity.properties ファイルはロギング、エンコーディング、マクロの設定を含みます。

The default configuration specifies the location of a 'global' Velocimacro template. This file can contain macros which will be made available to all templates.

デフォルトの設定では、 'グローバル' な Velocimacro テンプレートの配置情報が指定されています。このファイルには全てのテンプレートから利用できるマクロが含まれます。

The location of the configuration file is specified in web.xml, and it is recommended the file be placed inside the hidden WEB-INF directory of the web application. An example configuration file is included with the distribution.

この設定ファイルの場所は web.xml で指定します。また、このファイルは WEB-INF ディレクトリの中に配置するのが良いでしょう。サンプルの設定ファイルは配布物に含まれています。

Please see the Velocity User's Guide for more information on Velocity configuration.

Velocity の設定についての詳細は Velocity ユーザガイドを参照してください。

  velocimacro.library = /WEB-INF/VM_global_library.vm
  velocimacro.permissions.allow.inline = true
  velocimacro.permissions.allow.inline.to.replace.global = false
  velocimacro.permissions.allow.inline.local.scope = false  
  velocimacro.context.localscope = false

Toolboxの設定

The toolbox file, WEB-INF/toolbox.xml in our example, maps names of our choosing to the classes that they will represent. It's easier than that sounds.

サンプルのツールボックスファイル、 WEB-INF/toolbox.xml では、使用するクラスを好きな名前にマップしています。これは言うほど難しいものではありません。

Think about asking our friend Jon to grab us a 'wrench' from a real toolbox. Jon just needs to know which wrench we want (metric, pipe, crescent etc,). He doesn't need to know what the wrench does nor what we are planning to do with it.

友達のジョンに道具箱(toolbox)から 'レンチ' を取り出してもらうことについて考えてみます。ジョンはどの種類のレンチ (メトリック、パイプ、三日月) が必要なのか、ということだけを知っている必要があります。レンチをどのように使うかどうかは、彼は知る必要はありません。

The Velocity Toolbox works the same way, we must only specify which tool to assign to a name, and then the Velocity engine takes care of the rest by making any public method available to the template. For example, from the definitions below, the template could call $wrench.getSize() or $wrench.size .

Velocity のツールボックスも同じです。ツールが割り当てられてる名前を指定するだけで、 Velocity エンジンが全ての public メソッドをテンプレートから利用可能にしてくれます。例えばこのような定義を行うことで、テンプレートで $wrench.getSize() または $wrench.size という呼び出しが可能となります。

PipeWrench.java

public class PipeWrench {
  public String getSize() {
	return "Large Pipe Wrench!";
  }
}

public class PipeWrench {
  public String getSize() {
	return "でかいパイプレンチ!";
  }
}

toolbox.xml

<?xml version="1.0"?>
<toolbox>
  <tool>
     <key>wrench</key>
     <class>PipeWrench</class>
  </tool>
</toolbox>

Tool Scopes

Tool のスコープ

The toolbox support built into the VelocityViewServlet also provides support for specifying the scope of your tool with regards to the servlet environment. Tools may be placed within the request, session, or application scopes of your web app.

ツールボックスのサポートは VelocityViewServlet に組み込まれており、さらにサーブレット環境でのスコープの指定もサポートされています。ツールは リクエスト, セッション, アプリケーション スコープに配置されます。

The scope that you set for your tool will determine both its lifecycle and, if it implements the ViewTool interface, then the scope will also determine what data is passed to the init(Object) method:

ツールに設定したスコープにより、ツールのライフサイクルと、ツールが ViewTool を実装している場合に init(Object) メソッドにどのデータが渡されるかが決定されます:

application scoped tools will be instantiated only once and then reused for each request. Due to this, it is strongly encouraged that your application scoped tools be completely threadsafe. The MathTool in the GenericTools section is a good example of tool meant to be application scoped. If an application scoped tool implements ViewTool, then the javax.servlet.ServletContext for the webapp will be passed to its init(Object) method after it is instantiated.
session scoped tools are instantiated once per unique session and are then reused for every request associated with that particular session. If a session scoped tool implements ViewTool, then its init(Object) method will be passed the ViewContext of the request during which the session was created.
request is the default scope. If no scope is specified for a <tool> in your toolbox.xml, then it will be automatically set as request scope. Tools with this scope are instantiated for every servlet request fed to the VelocityViewServlet. If a request scoped tool implements ViewTool, then its init(Object) method will be passed the current ViewContext.

アプリケーション スコープのツールは、一回のみインスタンス化され、全てのリクエストに対し再利用されます。当然、アプリケーションスコープのツールはスレッドセーフである必要があります。 GenericTools の MathTool がアプリケーションスコープのツールの良い例です。アプリケーションスコープのツールが ViewTool を実装している場合、インスタンス化された後に Web アプリケーションの javax.servlet.ServletContext が init(Object) メソッドへ渡されます。
セッション スコープのツールは一つのセッションにつき一回インスタンス化され、同一セッションを持つリクエストに対して再利用されます。セッションスコープのツールが ViewTool を実装している場合、セッション作成時にリクエストの ViewContext がinit(Object) メソッドへ渡されます。
リクエスト はデフォルトのスコープとなります。 toolbox.xml の <tool> にスコープが指定されていない場合、自動的に リクエスト スコープへセットされます。このスコープのツールは VelocityViewServlet へリクエストが届くたびにインスタンス化されます。リクエストスコープのツールが ViewTool を実装している場合、現在のリクエストの ViewContext が init(Object) メソッドへ渡されます。

You can specify the scope of your tools by adding a <scope> element to your toolbox.xml entries like this:

ツールのスコープは toolbox.xml にこのように <scope> 要素を追加することによって指定することができます:

<tool>
   <key>math</key>
   <scope>application</scope>
   <class>org.apache.velocity.tools.generic.MathTool</class>
</tool>

In addition to specifiying arbitrary Java classes as tools to be automatically available to your templates, the toolbox support also includes the ability to specify arbitrary strings, booleans, and numbers to be automatically available in your templates. The format is as follows:

Java のクラスを ツールとして自動的にテンプレートへ提供することに加え、ツールボックスでは任意の String や boolean 、数値を指定しテンプレートへ提供することが可能です。フォーマットを以下に示します:

<?xml version="1.0"?>
<toolbox>
  <data type="number">
     <key>app_version</key>
     <value>0.9</value>
  </data>
  <data type="string">
     <key>app_name</key>
     <value>Jon's Tool Shop</value>
  </data>
  <data type="boolean">
     <key>debug</key>
     <value>true</value>
  </data>
</toolbox>

<?xml version="1.0"?>
<toolbox>
  <data type="number">
     <key>app_version</key>
     <value>0.9</value>
  </data>
  <data type="string">
     <key>app_name</key>
     <value>ジョンのツールショップ</value>
  </data>
  <data type="boolean">
     <key>debug</key>
     <value>true</value>
  </data>
</toolbox>

As with your tools, your data will be exposed to your templates under the specified key (e.g. $app_version, $app_name, $debug).

テンプレートでは、ツールやデータは指定されたキー (例: $app_version, $app_name, $debug) によってアクセスすることができます。

VelocityLayoutServlet

One derivative of the VelocityViewServlet is the VelocityLayoutServlet written by Nathan Bubna. This servlet performs a simplified 'two-pass render' in order to apply a shared, common layout to all of the web pages in an application.

Nathan Bubna 氏によって書かれた VelocityViewServlet の拡張実装が VelocityLayoutServlet です。このサーブレットは共通のレイアウトをアプリケーションの Web ページに適用するため、2段階の表示処理を行います。

The Struts "template" tag library does something similar, but requires a separate file to define which 'layout' file to use and which .jsp files to render into that layout. The VelocityLayoutServlet takes a simpler approach. It first renders the primary template being called (example: showDetails.vm) into a content holder variable (ex. $screen_content). Next, the servlet loads a 'layout' file. It uses the existing data, including any additional variables set or changed by the first template, to render a the layout template.

Struts の "template" タグライブラリは同じようなことを行いますが、どのレイアウトファイルを使い、どの .jsp ファイルを表示するかを別のファイルに定義する必要があります。 VelocityLayoutServlet はよりシンプルなアプローチです。 VelocityLayoutServlet は最初に呼び出されたメインのテンプレート (例: showDetails.vm) の表示内容を、専用の変数 (例: $screen_content) へ格納します。そして次に、レイアウトファイルをロードするのです。そして、メインテンプレートで変数が追加設定もしくは変更された、既存のデータをレイアウトテンプレートの表示に使用します。

The VelocityLayoutServlet also allows you to specify an 'error' template to be displayed when an exception is thrown during the processing of a requested template. This allows you to provide a customized error screen for a more user-friendly application.

VelocityLayoutServletは更にテンプレート処理中に例外が発生した場合、 'エラー'テンプレートを表示するように指定することができます。これにより、カスタマイズされたエラー画面を提供することができ、よりユーザフレンドリーなアプリケーションを作成できます。

Detailed documentation here: VelocityLayoutServlet.

詳細なドキュメントはこちら: VelocityLayoutServlet。

例

A simple application example has been included to demonstrate the use of the VelocityViewServlet with automatically loaded view tools.

ビューツールの自動ロード、 VelocityViewServlet の使い方を説明するシンプルなサンプルアプリケーションが含まれています。

To run the examples you need Tomcat 4.X (note: Tomcat 3.x may work) or a compatible servlet runner.

この例の実行には Tomcat 4.X (注: Tomcat 3.x でも恐らく動作します) またはそれに相当するサーブレットコンテナが必要です。

The build process automatically generates a ready-to-deploy simple.war archive file located in the examples subdirectory. Deploy (i.e. copy) this simple.war file to the webapps directory of your servlet runner and restart. Now point a web browser at the following url:

ビルドの段階で自動的にデプロイ可能な simple.war が examples サブディレクトリに生成されます。この simple.war ファイルをサーブレットコンテナの Web アプリケーションディレクトリへデプロイ (コピー) し、コンテナを再起動してください。そして、次の URL を Web ブラウザで開きましょう:

http://<your_server>:<port>/simple/

既知の問題点
	None! 既知の問題点はありません!

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