The Jakarta Project < Tools - View >

Velocity Tools

VelocityView

VelocityView Tools

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

LinkTool リファレンスドキュメント
       

The LinkTool provides methods to work with URIs:

LinkTool はURIに関するメソッドを提供します:

The LinkTool is somewhat special in that many of its methods return a new instance of LinkTool. This facilitates greatly the repeated use of the LinkTool in Velocity and leads to an elegant syntax.

LinkTool の持つ多くのメソッドが、新しい LinkTool のインスタンスを返却するという点は多少特殊です。 これは、 LinkTool の再利用を促進するとともに、エレガントな構文を提供します。

I've been struggling a bit to find the right terminology for the things that this tool works with. Based on document http://www.w3.org/Architecture/Terms, I have used:

私は、このツールが処理するものに適切な用語を見つけようと努力しました。 http://www.w3.org/Architecture/Terms、をドキュメントのベースとして利用しました。 用語はこれらを使用します:

URI
To refer to the full, absolute address of web resources, e.g. static documents or abstract resources like dynamically generated content. Example: http://myserver.org/myapp/templates/index.html
URI Reference
To refer to partial and relative URIs that reference a URI. Example: templates/index.html.
URL
Not used here.
URI
静的ドキュメントや、ダイナミックに生成されるコンテンツのような抽象的なリソースなどの Web リソースの完全な絶対アドレスを指します。 例: http://myserver.org/myapp/templates/index.html
URI リファレンス
URIを参照するための部分的・相対的なURIを指します。 例: templates/index.html
URL
使用しません。
Class
 org.apache.velocity.tools.view.tools.LinkTool
Name
 $link (Velocityコンテキスト内での推奨名)
Toolbox設定例
 
<tool>
  <key>link</key>
  <scope>request</scope>
  <class>org.apache.velocity.tools.view.tools.LinkTool</class>
</tool>
作者
 Gabriel Sidler
Nathan Bubna
Method Overview
setURI() Returns a copy of this LinkTool instance with the given URI reference.
setRelative() Returns a copy of this LinkTool instance with the specified context-relative URI reference converted to a server-relative URI reference.
addQueryData() Adds a key=value pair to the URI reference.
setAnchor() Sets an internal document reference to append to this link (e.g. #foo).
getURI() Returns the current URI reference.
getQueryData() Returns this instance's query data.
getContextURL() Returns the URI that addresses this web application.
getContextPath() Returns the context path that addresses this web application.
getBaseRef() Returns the full URI of this template.
toString() Returns the full URI that has been constructed. The session ID is encoded into the URL if cookies are not supported by the web client.
Method Overview
setURI() 与えられた URI リファレンスを、この LinkTool のインスタンスのコピーへ設定して返却します。
setRelative() 指定されたコンテキスト相対 URI リファレンスをサーバ相対 URI リファレンスへ変換し、この LinkTool のインスタンスのコピーへ設定して返却します。
addQueryData() URI リファレンスに key=value のペアを追加します。
setAnchor() 内部ドキュメントへのリファレンスをこのリンクへ追加します (例 #foo)。
getURI() 現在の URI リファレンスを返却します。
getQueryData() このインスタンスのクエリデータを返却します。
getContextURL() この Web アプリケーションを示す URI を返却します。
getContextPath() このウェブアプリケーションを示すコンテキストパスを返却します。
getBaseRef() このテンプレートの完全 URI を返却します。
toString() 構築された完全な URI を返却します。 クッキーをサポートしないウェブクライアントに対しては、セッション ID を URL の中に含めます。
setURI()
       

Returns a copy of this LinkTool instance with the given URI reference.

LinkTool setURI(String uri)

Parameters
uri
URI reference to set. The URI reference can be absolute (http://www.mydomain.com/myapp/templates/index.html), server-relative (/myapp/templates/index.html), relative (templates/index.html) and may contain query strings (templates/index.html?key1=value1&key2=value2).
Returns
A new instance of LinkTool.

No conversions are applied to the given URI reference. This method will overwrite any previously set URI reference but will copy query data set with method setQueryData().

## a relative reference
$link.setURI("index.html").addQueryData("key1","val 1")

## a server-relative reference
$link.setURI("/myapp/index.vm").addQueryData("key1","val 1")

## an absolute reference
$link.setURI("http://myserver.org/myapp/index.vm")
.addQueryData("key1", "val 1")

## a reference with a query string
$link.setURI("/myapp/index.vm?key0=val0")
.addQueryData("key1", "val 1")

This produces:

index.vm/key1=val+1
    
/myapp/index.vm/key1=val+1

http://myserver.org/myapp/index.vm?key1=val+1

/myapp/index.vm?key0=val0&key1=val+1

与えられた URI リファレンスを、この LinkTool のインスタンスのコピーへ設定して返却します。

LinkTool setURI(String uri)

Parameters
uri
設定する URI リファレンス。 URI リファレンスは絶対パス (http://www.mydomain.com/myapp/templates/index.html), サーバ相対パス (/myapp/templates/index.html), 相対パス (templates/index.html) であり、クエリストリングを含めることもできます (templates/index.html?key1=value1&key2=value2)。
Returns
LinkTool の新しいインスタンス。

与えられた URI リファレンスには何の変換も行われません。 このメソッドは前に設定されていた URI リファレンスを上書きしますが、 クエリデータはsetQueryData() メソッドを使用してコピーされます。

## 相対参照
$link.setURI("index.html").addQueryData("key1","val 1")

## サーバ相対参照
$link.setURI("/myapp/index.vm").addQueryData("key1","val 1")

## 絶対参照
$link.setURI("http://myserver.org/myapp/index.vm")
.addQueryData("key1", "val 1")

## クエリストリングを付加した参照
$link.setURI("/myapp/index.vm?key0=val0")
.addQueryData("key1", "val 1")

これは以下を出力します:

index.vm/key1=val+1
    
/myapp/index.vm/key1=val+1

http://myserver.org/myapp/index.vm?key1=val+1

/myapp/index.vm?key0=val0&key1=val+1
setRelative()
       

Returns a copy of this LinkTool instance with the specified context-relative URI reference converted to a server-relative URI reference.

LinkTool setRelative(String uri)

Parameters
uri
A context-relative URI reference, i.e. a URI reference that is relative to the URI used to address this web application.
Returns
A new instance of LinkTool.

The specified context-relative URI reference is converted to a server-relative URI reference. This method will overwrite any previously set URI reference but will copy the query string.


## a context-relative hyperlink
<a href="$link.setRelative("templates/index.vm").addQueryData("key1","val 1")">My Link</a>

Produces something like:

<a href="/myapp/templates/index.vm?key=val+1">My Link</a>

指定されたコンテキスト相対 URI リファレンスをサーバ相対 URI リファレンスへ変換し、この LinkTool のインスタンスのコピーへ設定して返却します。

LinkTool setRelative(String uri)

Parameters
uri
コンテキスト相対 URI リファレンス。 つまり、 Web アプリケーションからの相対 URI。
Returns
LinkTool の新しいインスタンス。

指定されたコンテキスト相対 URI リファレンスはサーバ相対 URI リファレンスへ変換されます。 このメソッドは前に設定されていた URI リファレンスを上書きしますが、 クエリデータはコピーされます。


## コンテキスト相対リンク
<a href="$link.setRelative("templates/index.vm").addQueryData("key1","val 1")">My Link</a>

以下のように出力されます:

<a href="/myapp/templates/index.vm?key=val+1">My Link</a>
addQueryData()
       

Adds a key=value pair to the URI reference.

LinkTool addQueryData(String key, Object value)

Parameters
key
Key (name) of query parameter.
value
Value of the query parameter. The string representation of this object is added to the query data.
Returns
A new instance of LinkTool.

Adds a key=value pair to the query data. This returns a new LinkTool containing both a copy of this LinkTool's query data and the new data. This makes repeated use in Velocity templates easy. Query data is URL-encoded before it is appended.

See method setURI() for examples.

URI リファレンスに key=value のペアを追加します。

LinkTool addQueryData(String key, Object value)

Parameters
key
クエリパラメータのキー(名前)。
value
クエリパラメータの値。 このオブジェクトの文字列表現がクエリデータに付加されます。
Returns
LinkTool の新しいインスタンス。

クエリデータに key=value のペアを追加します。 このメソッドは元の LinkTool のクエリデータと新規のデータ、 両方を含む新しい LinkTool を返却します。 これによって Velocity テンプレートにおいて[訳者補足：LinkTool インスタンスを]繰り返し利用することが容易になります。 クエリデータは追加される前に URL エンコードされます。

例は メソッド setURI() を参照してください。
setAnchor()
       

Sets an internal document reference to append to this link (e.g. #foo).

LinkTool setAnchor(String anchor)

Parameters
anchor
The internal document reference to append to this link
Returns
A new instance of LinkTool.

Returns a copy of the link with the specified anchor to be added to the end of the generated hyperlink. This returns a new LinkTool containing both a copy of this LinkTool's data and the new anchor value. This makes repeated use in Velocity templates easy. The anchor value is url encoded before being rendered.

内部ドキュメントへのリファレンスをこのリンクへ追加します (例 #foo)。

LinkTool setAnchor(String anchor)

Parameters
anchor
リンクへ追加する内部ドキュメントへのリファレンス。
Returns
LinkTool の新しいインスタンス。

生成されるリンクの最後に指定したアンカを追加した、 リンクのコピーを返却します。このメソッドは元の LinkTool の データと、新しいアンカの値を含む、新規の LinkTool を返却します。 これによって Velocity テンプレートにおいて[訳者補足：LinkTool インスタンスを]繰り返し利用することが容易になります。 アンカの値は表示される前に URL エンコードされます。
getURI()
       

Returns the current URI reference.

LinkTool getURI()

Returns
Returns the current URI reference as set by one of the methods setURI() or setRelative(). Any conversions have been applied. The returned URI reference does not included query data that was added with method addQueryData().
See Also
Method getQueryData() to retrieve query data only. Method toString() to retrieve the URI reference including all query data. 
#set ($l = $link.setForward("start").addQueryData("key1","val 1"))
<a href="$l.getURI()">My Link</a>

Produces something like:

<a href="/myapp/templates/index.vm">My Link</a>

現在の URI リファレンスを返却します。

LinkTool getURI()

Returns
setURI() や setRelative() などのメソッドによって設定された現在の URI リファレンスを返却します。 必要な変換は全て行われます。 返却される URI リファレンスは addQueryData() メソッドで付加されたクエリデータを含みません。
See Also
クエリデータのみを返却する getQueryData() メソッド。 クエリデータを含む URI リファレンスを返却する toString() メソッド。 
#set ($l = $link.setForward("start").addQueryData("key1","val 1"))
<a href="$l.getURI()">My Link</a>

以下のように出力されます:

<a href="/myapp/templates/index.vm">My Link</a>
getQueryData()
       

Returns this instance's query data.

String getQueryData()

Returns
This instance's query data as set by the method setQueryData(). The returned String is URL-encoded, e.g. "key=value&foo=this+is+encoded". 
#set ($l = $link.setForward("start").addQueryData("key1","val 1"))
$l.getQueryData()

Produces:

key1=val+1

このインスタンスのクエリデータを返却します。

String getQueryData()

Returns
setQueryData() メソッドで設定されたこのインスタンスのクエリデータ。 返却される String は URL エンコードされたものです。 例: "key=value&foo=this+is+encoded"。 
#set ($l = $link.setForward("start").addQueryData("key1","val 1"))
$l.getQueryData()

出力:

key1=val+1
getContextURL()
       

Returns the URI that addresses this web application.

String getContextURL()

Returns
Returns the URI reference that addresses this web application, e.g. "http://myserver.net/myapp". This string does not end with a "/".

Note! This will not represent the URI reference or query data set for this LinkTool instance.

$link.getContextURL()

Produces something like:

http://myserver.net/myapp

この Web アプリケーションを示す URI を返却します。

String getContextURL()

Returns
このウェブアプリケーションを示す URI を返却します。 例: "http://myserver.net/myapp"。 返却される文字列の最後には "/" が付加されません。

注意! これはこの LinkTool インスタンスの URI リファレンスやクエリデータを表すものではありません。

$link.getContextURL()

以下のように出力されます:

http://myserver.net/myapp
getContextPath()
       

Returns the context path that addresses this web application.

String getContextPath()

Returns
The context path that addresses this web application, e.g. "/myapp". This string starts with a "/" but does not end with a "/".

Note! This will not represent the URI reference or query data set for this LinkTool instance.

$link.getContextPath()

Produces something like:

/myapp

このウェブアプリケーションを示すコンテキストパスを返却します。

String getContextPath()

Returns
このウェブアプリケーションを示すコンテキストパス。 例: "/myapp"。 返却される文字列は "/" で始まりますが、最後には "/" が付加されません。

注意! これはこの LinkTool インスタンスの URI リファレンスやクエリデータを表すものではありません。

$link.getContextPath()

以下のように出力されます:

/myapp
getBaseRef()
       

Returns the full URI of this template.

String getBaseRef()

Returns
The full URI of this template without any query data. e.g. http://myserver.net/myapp/templates/View.vm.

Note! The returned String will not represent the URI reference or query data set for this LinkTool instance. A typical application of this method is with the HTML base tag.

## a base tag
<base href="$link.getBaseRef()">

Produces something like:

<base href="http://myserver.net/myapp/templates/index.vm">

このテンプレートの完全 URI を返却します。

String getBaseRef()

Returns
クエリデータを含まないこのテンプレートの完全 URI 。 例: http://myserver.net/myapp/templates/View.vm。

注意! これはこの LinkTool インスタンスの URI リファレンスやクエリデータを表すものではありません。 このメソッドは通常、 HTML の base タグに使用します。

## base タグ
<base href="$link.getBaseRef()">

以下のように出力されます:

<base href="http://myserver.net/myapp/templates/index.vm">
toString()
       

Returns the full URI that has been constructed. The session ID is encoded into the URL if cookies are not supported by the web client.

String toString()

Returns
The full URI that has been built with this tool e.g. /myapp/stuff/View.vm?id=42&type=blue#foobar.

Typically it is not necessary to call this method explicitly. Velocity will call the toString() method automatically to obtain a representable version of objects.

<a href="$link.setRelative("demo").addQueryString("key1", "val 1")">
My Link</a>

Produces something like:

<a href="/myapp/demo.do?key1=val+1">My Link</a>

If sessions are used and the web client does not support cookies, the toString() method automatically encodes the session ID into the returned URI. The above example would then produce something like: 

<a href="/myapp/demo.do;jsessionid=aaaaaaanisPWVYEY01?key1=val+1">
My Link</a>

A Note about URI Encoding

URI encoding is about encoding the session ID into the URI string. This section briefly explains the reasoning behind it and how it works.

Many web applications use sessions to associate an application state with a particualar user. For example, a session might be used to maintain the state of a shopping cart while the user is browsing the online shop.

The Servlet API has forseen two mechanisms to identify HTTP requests that belong to a particular session.

  • Cookies: A new cookie containing the session ID is sent to the client at the beginning of a session. The client returns this cookie with every request.
  • URI Encoding: The session ID is encoded into the URI string. The server parses the URI of requests to detect the presence of an encoded session ID.

Most developers prefer to use cookies to identify sessions. The cookie-based mechanism is easier to work with because it does not require the encoding of every URI. However, for reasons of security and privacy some users choose to disable cookie support in their browsers. If session management relies on cookies only, it will fail in such a situation. A well designed web application needs to be able to fall back to the URI encoding method in this case.

The Servlet API offers two methods to support the web application developer with the URI encoding:

java.lang.String encodeURL(java.lang.String url)
java.lang.String encodeRedirectURL(java.lang.String url)

These two methods encode the sesssion id into the URI string if sessions are used and if the particular web client does not support cookies.

The toString() method of LinkTool automatically does URI encoding using the encodeURL() method. Therefore, if all URIs within an application are produced with the LinkTool, the application is able to work properly with or without cookie support of the client.

The following examples show the output of the toString() method if cookies are enabled and disabled.

<a href="$link.setURI("MyPage.vm").addQueryData("key1","val 1")">
My Link</a>

<form name="MyForm" method="post" action="$link.setURI("MyPage.vm")">

Produces this if cookies are enabled:

<a href="MyPage.vm?key1=val+1">My Link</a>

<form name="MyForm" method="post" action="MyPage.vm">

Produces something like this if cookies are diabled:

<a href="MyPage.vm;jsessionid=E9833012F7B2F8570963B137?key1=val+1">
My Link</a>

<form name="MyForm" method="post" 
action="MyPage.vm;jsessionid=E9833012F7B20857096F37743B137">

構築された完全な URI を返却します。 クッキーをサポートしないウェブクライアントに対しては、セッション ID を URL の中に含めます。

String toString()

Returns
このツールで構築された完全な URI を返却します。 例: /myapp/stuff/View.vm?id=42&type=blue#foobar。

通常、このメソッドを明示的に呼ぶ必要はありません。 Velocity は、オブジェクトの文字列表現を取得するために toString() メソッドを自動的に呼びだします。

<a href="$link.setRelative("demo").addQueryString("key1", "val 1")">
My Link</a>

以下のように出力されます:

<a href="/myapp/demo.do?key1=val+1">My Link</a>

ウェブクライアントがクッキーをサポートしない場合にセッションを使用すると、 toString() メソッドは自動的にセッションIDを、返却する URI へ含めます。 上の例は以下のようなものを生成します: 

<a href="/myapp/demo.do;jsessionid=aaaaaaanisPWVYEY01?key1=val+1">
My Link</a>

URI エンコーディングについて

URI エンコーディング とはセッションIDを URI 文字列中へ含めるものです。 この章では、この理由と、これがどのような動きとなるかについて簡単に説明します。

多くの Web アプリケーションは、特定のユーザとアプリケーションの状態を関連づけるためにセッションを利用します。 例えば、ユーザがオンラインショップをブラウジングしている間、ショッピングカートの状態を保持するためにセッションが利用されます。

Servlet API には、特定のセッションに属する HTTP リクエストを識別するための、2つの仕組みがあります。

  • クッキー: セッションの開始時に、 セッションIDを含む新しいクッキーがクライアントに送られます。 クライアントはすべてのリクエストにこのクッキーをを付加して返却します。
  • URI エンコーディング(訳者注: URL Rewriting、URL 書き換え): セッションIDは URI へエンコードされます。 サーバはリクエストの URI を解析し、セッションIDを検出します。

多くの開発者は、セッションの識別にクッキーを使用することを選びます。 すべてのURIをエンコードする、ということが不要なので、クッキーベースの仕組みの方が簡単だからです。 しかし、セキュリティやプライバシーの問題から、ブラウザのクッキーのサポートを無効にしているユーザも存在します。 セッション管理がクッキーのみで行われている場合、上記のようなユーザに対してはセッション管理ができません。 こういったケースでも、良い設計がされているウェブアプリケーションならば、フォールバック(訳者注: 代替)として URI エンコーディングによる方法が機能します。

Servlet API は URI エンコーディングをサポートする2つのメソッドをウェブアプリケーション開発者へ提供しています。

java.lang.String encodeURL(java.lang.String url)
java.lang.String encodeRedirectURL(java.lang.String url)

この2つのメソッドは、もし、セッションを使用していて、かつ、ウェブクライアントがクッキーをサポートしていない場合に、セッションIDを URI に含めます。

LinkTool の toString() メソッドは encodeURL() メソッドを使用し、自動的に URI エンコーディングを行います。 したがって、アプリケーション中のすべての URI が LinkTool によって生成されている場合、アプリケーションはクライアントのクッキーのサポート有無にかかわらず、適切に動作するでしょう。

以下はクッキーが有効/無効時の toString() メソッドの出力例です。

<a href="$link.setURI("MyPage.vm").addQueryData("key1","val 1")">
My Link</a>

<form name="MyForm" method="post" action="$link.setURI("MyPage.vm")">

クッキー有効時の出力:

<a href="MyPage.vm?key1=val+1">My Link</a>

<form name="MyForm" method="post" action="MyPage.vm">

クッキー無効時の出力はこのようになります:

<a href="MyPage.vm;jsessionid=E9833012F7B2F8570963B137?key1=val+1">
My Link</a>

<form name="MyForm" method="post" 
action="MyPage.vm;jsessionid=E9833012F7B20857096F37743B137">
[訳注: この文書は 木村 貴由 野瀬 直樹 が翻訳しました。 日本語訳に対するコメントがあれば、report@jajakarta.orgに送って下さい。]
Copyright © 1999-2003, Apache Software Foundation