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

• サーバ相対 URI を設定します。 setRelative()
• 任意の URI を設定します。 setURI()
• クエリストリングの構築とエンコードを行います。 addQueryData() と getQueryData() メソッドを参照してください。
• 内部アンカリファレンスを設定する setAnchor()
• URL へセッションIDをエンコードします。 toString() メソッドを参照してください。
• サーバ名とポートとパスを処理中のリクエストへ格納します。 getURI(), getContextURL(), getContextPath() と getBaseRef() メソッドを参照してください。

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

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

URI

静的ドキュメントや、ダイナミックに生成されるコンテンツのような抽象的なリソースなどの Web リソースの完全な絶対アドレスを指します。 例: http://myserver.org/myapp/templates/index.html

URI リファレンス

URIを参照するための部分的・相対的なURIを指します。 例: templates/index.html

URL

使用しません。

<tool>
  <key>link</key>
  <scope>request</scope>
  <class>org.apache.velocity.tools.view.tools.LinkTool</class>
</tool>

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 の中に含めます。

与えられた 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

指定されたコンテキスト相対 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>

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

LinkTool addQueryData(String key, Object value)

Parameters

key

クエリパラメータのキー(名前)。

value

クエリパラメータの値。 このオブジェクトの文字列表現がクエリデータに付加されます。

Returns

LinkTool の新しいインスタンス。

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

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

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

LinkTool setAnchor(String anchor)

Parameters

anchor

リンクへ追加する内部ドキュメントへのリファレンス。

Returns

LinkTool の新しいインスタンス。

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

現在の 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>

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

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

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

String getContextURL()

Returns

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

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

$link.getContextURL()

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

http://myserver.net/myapp

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

String getContextPath()

Returns

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

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

$link.getContextPath()

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

/myapp

このテンプレートの完全 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">

構築された完全な 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">