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、をドキュメントのベースとして利用しました。 用語はこれらを使用します:
http://myserver.org/myapp/templates/index.htmltemplates/index.html. http://myserver.org/myapp/templates/index.htmltemplates/index.htmlhttp://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).
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().
This produces:
http://www.mydomain.com/myapp/templates/index.html), サーバ相対パス (/myapp/templates/index.html), 相対パス (templates/index.html) であり、クエリストリングを含めることもできます (templates/index.html?key1=value1&key2=value2)。
LinkTool の新しいインスタンス。
与えられた URI リファレンスには何の変換も行われません。
このメソッドは前に設定されていた URI リファレンスを上書きしますが、
クエリデータはsetQueryData() メソッドを使用してコピーされます。
これは以下を出力します:
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.
Produces something like:
LinkTool の新しいインスタンス。
指定されたコンテキスト相対 URI リファレンスはサーバ相対 URI リファレンスへ変換されます。 このメソッドは前に設定されていた URI リファレンスを上書きしますが、 クエリデータはコピーされます。
以下のように出力されます:
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.
LinkTool の新しいインスタンス。
クエリデータに key=value のペアを追加します。 このメソッドは元の LinkTool のクエリデータと新規のデータ、 両方を含む新しい LinkTool を返却します。 これによって Velocity テンプレートにおいて[訳者補足：LinkTool インスタンスを]繰り返し利用することが容易になります。 クエリデータは追加される前に URL エンコードされます。
例は メソッド setURI() を参照してください。
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.
LinkTool の新しいインスタンス。
生成されるリンクの最後に指定したアンカを追加した、 リンクのコピーを返却します。このメソッドは元の LinkTool の データと、新しいアンカの値を含む、新規の LinkTool を返却します。 これによって Velocity テンプレートにおいて[訳者補足：LinkTool インスタンスを]繰り返し利用することが容易になります。 アンカの値は表示される前に URL エンコードされます。
getQueryData() to retrieve
query data only. Method toString() to
retrieve the URI reference including all query data.
Produces something like:
getQueryData() メソッド。
クエリデータを含む URI リファレンスを返却する toString() メソッド。
以下のように出力されます:
setQueryData(). The
returned String is URL-encoded, e.g. "key=value&foo=this+is+encoded".
Produces:
setQueryData() メソッドで設定されたこのインスタンスのクエリデータ。
返却される String は URL エンコードされたものです。
例: "key=value&foo=this+is+encoded"。
出力:
Note! This will not represent the URI reference or query data set for this LinkTool instance.
Produces something like:
注意! これはこの LinkTool インスタンスの URI リファレンスやクエリデータを表すものではありません。
以下のように出力されます:
"/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.
Produces something like:
"/myapp"。
返却される文字列は "/" で始まりますが、最後には "/" が付加されません。
注意! これはこの LinkTool インスタンスの URI リファレンスやクエリデータを表すものではありません。
以下のように出力されます:
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.
Produces something like:
http://myserver.net/myapp/templates/View.vm。
注意! これはこの LinkTool インスタンスの URI リファレンスやクエリデータを表すものではありません。 このメソッドは通常、 HTML の base タグに使用します。
以下のように出力されます:
/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.
Produces something like:
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 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.
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.
Produces this if cookies are enabled:
Produces something like this if cookies are diabled:
/myapp/stuff/View.vm?id=42&type=blue#foobar。
通常、このメソッドを明示的に呼ぶ必要はありません。 Velocity は、オブジェクトの文字列表現を取得するために toString() メソッドを自動的に呼びだします。
以下のように出力されます:
ウェブクライアントがクッキーをサポートしない場合にセッションを使用すると、 toString() メソッドは自動的にセッションIDを、返却する URI へ含めます。
上の例は以下のようなものを生成します:
URI エンコーディングについて
URI エンコーディング とはセッションIDを URI 文字列中へ含めるものです。 この章では、この理由と、これがどのような動きとなるかについて簡単に説明します。
多くの Web アプリケーションは、特定のユーザとアプリケーションの状態を関連づけるためにセッションを利用します。 例えば、ユーザがオンラインショップをブラウジングしている間、ショッピングカートの状態を保持するためにセッションが利用されます。
Servlet API には、特定のセッションに属する HTTP リクエストを識別するための、2つの仕組みがあります。
多くの開発者は、セッションの識別にクッキーを使用することを選びます。 すべての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() メソッドの出力例です。
クッキー有効時の出力:
クッキー無効時の出力はこのようになります: