The LinkTool provides many methods to work with URIs and can help you:

construct full URIs (opaque, absolute or relative)

encode and decode URLs (part or whole)

retrieve path info for the current request

and more..

This GenericTools (i.e. non-servlet based) version of LinkTool
is largely based upon the same API and behavior as the older
VelocityView version, with a few differences, particularly in
internal representation and query handling. You can expect that
in the future work will be done to more closely align the APIs.
It is likely that the VelocityView version will become a subclass
of this version that adds on servlet-awareness and related features.
For now, though, they are entirely separate but similar tools.

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

duplicate

Equivalent to clone, but with no checked exceptions.
If for some unfathomable reason clone() doesn't work,
this will throw a RuntimeException. If doing a deep
clone, then the parameter Map will also be cloned.

setQuery

If the specified value is null, it will set the query to null.
If a Map, it will copy all those values into a new LinkedHashMap and
replace any current query value with that. If it is a String,
it will use parseQuery(String) to parse it into a map
of keys to values.

setParam

If there is no existing value for this key in the query, it
will simply add it and its value to the query. If the key
already is present in the query and append
is true, this will add the specified value to those
already under that key. If appendParams is
false, this will override the existing values with the
specified new value.

setParams

If append is false, this simply delegates to setQuery(java.lang.Object).
Otherwise, if the specified object is null, it does nothing. If the object
is not a Map, it will turn it into a String and use parseQuery(java.lang.String) to
parse it. Once it is a Map, it will iterate through the entries appending
each key/value to the current query data.

combineQuery

If the second param is null or empty, this will simply return the first
and vice versa. Otherwise, it will trim any '?'
at the start of the second param and any '&' or '&amp;' at the
end of the first one, then combine the two, making sure that they
are separated by only one delimiter.

toQuery

Turns the specified key and value into a properly encoded
query pair string. If the value is an array or List, then
this will create a delimited string of query pairs, reusing
the same key for each of the values separately.

parseQuery

This will use the specified query delimiter to parse the specified
query string into a map of keys to values.
If there are multiple query pairs in the string that have the same
key, then the values will be combined into a single List value
associated with that key.

setFragment

setFromURI

If the specified value is null, this will set the scheme, userInfo,
host, port, path, query, and fragment all to their null-equivalent
values. Otherwise, this will
convert the specified object into a URI, then those same
values from the URI object to this instance, when not null or empty.
In other words, when given a URI this will only set values present
in the URI.

getHost

port

Returns a new instance with the specified value set
as its port number. If the value cannot be parsed into
an integer, the returned instance will always return
null for toString() and other
createURI()-dependent methods to alert the user
to the error.

getFile

getRoot

Returns the "root" for this URI, if it has one.
This does not stick close to URI dogma and will
try to insert the default scheme if there is none,
and will return null if there is no host or if there
was an error when the port value was last set. It will
return null for any opaque URLs as well, as those have
no host or port.

relative

relative

Returns a copy of the link with the specified directory-relative
URI reference set as the end of the path and setForceRelative(boolean)
set to true. If the specified relative path is null, that is treated
the same as an empty path.

absolute

Returns a copy of the link with the specified URI reference
either used as or converted to an absolute (non-relative)
URI reference. Unless the specified URI contains a query
or anchor, those values will not be overwritten when using
this method.

uri

Returns a copy of the link with the given URI reference set.
Few changes are applied to the given URI reference. The URI
reference can be absolute, server-relative, relative and may
contain query parameters. This method will overwrite all previous
settings for scheme, host port, path, query and anchor.

getBaseRef

Returns the full URI of this template without any query data.
e.g. http://myserver.net/myapp/stuff/View.vm
Note! The returned String will not represent any URI reference
or query data set for this LinkTool. A typical application of
this method is with the HTML base tag. For example:
<base href="$link.baseRef">

getQuery

param

Adds a key=value pair to the query data. Whether
this new query pair is appended to the current query
or overwrites any previous pair(s) with the same key
is controlled by the getAppendParams() value.
The default behavior is to append.

params

This method can do two different things. If you pass in a
boolean, it will create a new LinkTool duplicate and call
handleParamsBoolean(boolean) on it. In this class, true
values do nothing (subclasses may have use for them), but false
values will clear out all params in the query for that instance.
If you pass in a query string or a Map of parameters, those
values will be added to the new LinkTool, either overwriting
previous value(s) with those keys or appending to them,
depending on the getAppendParams() value.

getAnchor

getSelf

toString

Returns the full URI reference that's been built with this tool,
including the query string and anchor, e.g.
http://myserver.net/myapp/stuff/View.vm?id=42&type=blue#foo.
Typically, it is not necessary to call this method explicitely.
Velocity will call the toString() method automatically to obtain
a representable version of an object.

decodeQueryPercents

This is an ugly (but fast) hack that's needed because URI encodes
things that we don't need encoded while not encoding things
that we do need encoded. So, we have to encode query data
before creating the URI to ensure they are properly encoded,
but then URI encodes all the % from that encoding. Here,
we isolate the query data and manually decode the encoded
%25 in that section back to %, without decoding anything else.