The LinkTool provides methods to work with URIs:

• set server relative URIs setRelative()
• set arbitrary URIs setURI()
• construct and encode query strings, see methods addQueryData() and getQueryData()
• set internal anchor references setAnchor()
• encode session ID into URL, see method toString()
• retrieve server, port and path info for the current request, see methods getURI(), getContextURL(), getContextPath() and getBaseRef()

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:

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.

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

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.

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

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>

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.

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.

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>

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

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

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

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">

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">