The LinkTool provides methods to work with URIs:
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.
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://myserver.org/myapp/templates/index.html
templates/index.html
. 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
).
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:
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
.
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.
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.
getQueryData()
to retrieve
query data only. Method toString()
to
retrieve the URI reference including all query data.
Produces something like:
setQueryData()
. The
returned String is URL-encoded, e.g. "key=value&foo=this+is+encoded".
Produces:
Note! This will not represent the URI reference or query data set for this LinkTool instance.
Produces something like:
"/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:
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:
/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: