org.apache.velocity.tools.generic

## Class LinkTool

- java.lang.Object
- - org.apache.velocity.tools.generic.SafeConfig
  - - org.apache.velocity.tools.generic.LinkTool

All Implemented Interfaces:
  Serializable, Cloneable

    @DefaultKey(value="link")
     @SkipSetters
     @ValidScope(value="request")
    public class LinkTool
    extends SafeConfig
    implements Cloneable, Serializable

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.

Template example(s):

       #set( $base = $link.relative('MyPage.vm').anchor('view') )
       <a href="$base.param('select','this')">this</a>
       <a href="$base.param('select','that')">that</a>

     Toolbox configuration:
     <tools>
       <toolbox scope="request">
         <tool class="org.apache.velocity.tools.generic.LinkTool"
                  uri="http://velocity.apache.org/tools/devel/"/>
       </toolbox>
     </tools>

Since:
  VelocityTools 2.0
Version:
  $Id: LinkTool.java 601976 2007-12-07 03:50:51Z nbubna $
Author:
  Nathan Bubna
See Also:
  Serialized Form

### Field Summary

Fields
`static String` `APPEND_PARAMS_KEY`
`protected boolean` `appendParams`
`protected String` `charset`
`static String` `CHARSET_KEY`
`static String` `DEFAULT_CHARSET`
`static String` `DEFAULT_SCHEME`
`static String` `FORCE_RELATIVE_KEY`
`protected boolean` `forceRelative`
`protected String` `fragment`
`static String` `FRAGMENT_KEY`
`protected String` `host`
`static String` `HOST_KEY`
`static String` `HTML_QUERY_DELIMITER` Standard HTML delimiter for query data ('&')
`protected boolean` `opaque`
`protected String` `path`
`static String` `PATH_KEY`
`protected int` `port`
`static String` `PORT_KEY`
`protected Map` `query`
`static String` `QUERY_KEY`
`protected String` `queryDelim`
`protected String` `scheme`
`static String` `SCHEME_KEY`
`static String` `SECURE_SCHEME`
`protected LinkTool` `self`
`static String` `URI_KEY`
`protected String` `user`
`static String` `USER_KEY`
`static String` `XHTML_MODE_KEY`
`static String` `XHTML_QUERY_DELIMITER` XHTML delimiter for query data ('&amp;')

### Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

`LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY`

### Constructor Summary

Constructors
Constructor and Description
`LinkTool()` Default constructor.

### Method Summary

All Methods Instance Methods Concrete Methods
`LinkTool` `absolute()` Returns a copy of this LinkTool instance that has `setForceRelative(boolean)` set to false and sets the scheme to the "http" if no scheme has been set yet.
`LinkTool` `absolute(Object obj)` Returns a copy of the link with the specified URI reference either used as or converted to an absolute (non-relative) URI reference.
`LinkTool` `anchor(Object anchor)` Returns a copy of the link with the specified anchor to be added to the end of the generated hyperlink.
`LinkTool` `append(Object pth)` Appends the given value to the end of the current path value.
`LinkTool` `append(Object key, Object value)` Appends a new key=value pair to the existing query data.
`protected void` `appendAsArray(StringBuilder out, Object key, Object[] arr)`
`void` `appendPath(Object obj)` Uses `combinePath(java.lang.String, java.lang.String)` to add the specified value to the current `getPath()` value.
`void` `appendQuery(Object obj)` Uses `combineQuery(java.lang.String, java.lang.String)` to append the specified value to the current `getQuery()` value.
`protected String` `combinePath(String start, String end)` If end is null, this will return start and vice versa.
`protected String` `combineQuery(String current, String add)` If the second param is null or empty, this will simply return the first and vice versa.
`protected void` `configure(ValueParser props)` Configuration
`protected URI` `createURI()` Tries to create a URI from the current port, opacity, scheme, userInfo, host, path, query and fragment set for this instance, using the `URI` constructor that is appropriate to the opacity.
`String` `decode(Object obj)` Delegates decoding of the specified url content to `URLDecoder.decode(java.lang.String)` using the configured character encoding.
`protected String` `decodeQueryPercents(String url)` 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.
`LinkTool` `directory()` Returns a new LinkTool instance with the path set to the result of `getDirectory()` and the query and fragment set to null.
`protected LinkTool` `duplicate()` Equivalent to clone, but with no checked exceptions.
`protected LinkTool` `duplicate(boolean deep)` Equivalent to clone, but with no checked exceptions.
`String` `encode(Object obj)` Delegates encoding of the specified url content to `URLEncoder.encode(java.lang.String)` using the configured character encoding.
`boolean` `equals(Object obj)` This instance is considered equal to any LinkTool instance whose toString() method returns a String equal to that returned by this instance's toString()
`String` `getAnchor()` Returns the anchor (internal document reference) set for this link.
`boolean` `getAppendParams()` Returns true if `param(Object,Object)` appends values; false if the method overwrites existing value(s) for the specified key.
`String` `getBaseRef()` Returns the full URI of this template without any query data.
`String` `getCharacterEncoding()` Returns the configured charset used by the `encode(java.lang.Object)` and `decode(java.lang.Object)` methods.
`String` `getContextPath()` At this level, this only returns the result of `getDirectory()`.
`String` `getDirectory()` Returns the directory stack in the set `getPath()` value, by just trimming off all that follows the last "/".
`String` `getFile()` Returns the last section of the path, which is all that follows the final "/".
`String` `getHost()` Return the host value for this instance.
`Map` `getParams()`
`String` `getPath()` Returns the current path value for this instance.
`Integer` `getPort()` Returns the port value, if any.
`String` `getQuery()` Returns the current query as a string, if any.
`String` `getRoot()` Returns the "root" for this URI, if it has one.
`String` `getScheme()` Return the scheme value for this instance.
`LinkTool` `getSelf()`
`URI` `getUri()` If the tool is not in "safe mode"--which it is by default-- this will return the `URI` representation of this instance, if any.
`String` `getUser()` Returns the `URI.getUserInfo()` value for this instance.
`protected void` `handleParamsBoolean(boolean keep)` In this class, this method ignores true values.
`int` `hashCode()` Returns the hash code for the result of toString().
`LinkTool` `host(Object host)` Returns a new instance with the specified value set as its host.
`LinkTool` `insecure()` Returns a new instance with the scheme set to "http".
`boolean` `isAbsolute()` Returns true if this instance has a scheme value and is not being forced to create relative URIs.
`boolean` `isOpaque()` Returns true if this instance represents an opaque URI.
`boolean` `isRelative()` Returns true if this instance is being forced to return relative URIs or has a null scheme value.
`boolean` `isSecure()` Returns true if this instance's scheme is "https".
`boolean` `isXHTML()` Returns true if the query delimiter used by this instance is using `&amp;` as the delimiter for query data pairs or just using `&`.
`protected String` `normalizeQuery(String qs)`
`LinkTool` `param(Object key, Object value)` Adds a key=value pair to the query data.
`LinkTool` `params(Object parameters)` This method can do two different things.
`protected Map<String,Object>` `parseQuery(String query)` Uses `normalizeQuery(java.lang.String)` to make all delimiters in the specified query string match the current query delimiter and then uses `parseQuery(String,String)` to parse it according to that same delimiter.
`protected Map<String,Object>` `parseQuery(String query, String queryDelim)` This will use the specified query delimiter to parse the specified query string into a map of keys to values.
`LinkTool` `path(Object pth)` Returns a new instance with the specified value set as its path.
`LinkTool` `port(Object port)` Returns a new instance with the specified value set as its port number.
`LinkTool` `query(Object query)` Sets the specified value as the current query data, after normalizing the pair delimiters.
`LinkTool` `relative()` Returns a copy of this LinkTool instance that has `setForceRelative(boolean)` set to true.
`LinkTool` `relative(Object obj)` 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.
`LinkTool` `remove(Object key)` Returns a new LinkTool instance that has any value(s) under the specified key removed from the query data.
`Object` `removeParam(Object key)` Removes the query pair(s) with the specified key from the query data and returns the remove value(s), if any.
`LinkTool` `root()` Returns a new LinkTool instance that represents the "root" of the current one, if it has one.
`LinkTool` `scheme(Object scheme)` Returns a new instance with the specified value set as its scheme.
`LinkTool` `secure()` Returns a new instance with the scheme set to "https".
`LinkTool` `set(Object key, Object value)` Sets a new key=value pair to the existing query data, overwriting any previous pair(s) that have the same key.
`void` `setAppendParams(boolean addParams)` Sets whether or not the `setParam(java.lang.Object, java.lang.Object, boolean)` method will override existing query values for the same key or simply append the new value to a list of existing values.
`void` `setCharacterEncoding(String chrst)`
`void` `setForceRelative(boolean forceRelative)` Sets whether or not the `createURI()` method should ignore the scheme, user, port and host values for non-opaque URIs, thus making `toString()` print the link as a relative one, not an absolute one.
`void` `setFragment(Object obj)` Sets the anchor for this instance and treats empty strings like null.
`protected boolean` `setFromURI(Object obj)` If the specified value is null, this will set the scheme, userInfo, host, port, path, query, and fragment all to their null-equivalent values.
`void` `setHost(Object obj)` Sets host
`void` `setParam(Object key, Object value, boolean append)` If there is no existing value for this key in the query, it will simply add it and its value to the query.
`void` `setParams(Object obj, boolean append)` If append is false, this simply delegates to `setQuery(java.lang.Object)`.
`void` `setPath(Object obj)` If this instance is not opaque and the specified value does not start with a '/' character, then that will be prepended automatically.
`void` `setPort(Object obj)` If the specified object is null, this will set the port value to -1 to indicate that.
`void` `setQuery(Object obj)` If the specified value is null, it will set the query to null.
`void` `setScheme(Object obj)` This will treat empty strings like null values and will trim any trailing ':' character.
`void` `setUserInfo(Object obj)` Sets user info
`void` `setXHTML(boolean xhtml)` Controls the delimiter used for separating query data pairs.
`String` `toQuery(Map parameters)` Converts the map of keys to values into a query string.
`protected String` `toQuery(Object key, Object value)` Turns the specified key and value into a properly encoded query pair string.
`String` `toString()` Returns the full URI reference that's been built with this tool, including the query string and anchor, e.g.
`protected URI` `toURI(Object obj)` Turns the specified object into a string and thereby a URI.
`LinkTool` `uri(Object uri)` Returns a copy of the link with the given URI reference set.
`LinkTool` `user(Object info)` Returns a new instance with the specified value set as its user info.

### Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

`configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Field Detail

#### HTML_QUERY_DELIMITER

    public static final String HTML_QUERY_DELIMITER

Standard HTML delimiter for query data ('&')

See Also:
  Constant Field Values

#### XHTML_QUERY_DELIMITER

    public static final String XHTML_QUERY_DELIMITER

XHTML delimiter for query data ('&amp;')

See Also:
  Constant Field Values

#### APPEND_PARAMS_KEY

    public static final String APPEND_PARAMS_KEY

See Also:
  Constant Field Values

#### FORCE_RELATIVE_KEY

    public static final String FORCE_RELATIVE_KEY

See Also:
  Constant Field Values

#### DEFAULT_CHARSET

    public static final String DEFAULT_CHARSET

See Also:
  Constant Field Values

#### DEFAULT_SCHEME

    public static final String DEFAULT_SCHEME

See Also:
  Constant Field Values

#### SECURE_SCHEME

    public static final String SECURE_SCHEME

See Also:
  Constant Field Values

#### URI_KEY

    public static final String URI_KEY

See Also:
  Constant Field Values

#### SCHEME_KEY

    public static final String SCHEME_KEY

See Also:
  Constant Field Values

#### USER_KEY

    public static final String USER_KEY

See Also:
  Constant Field Values

#### HOST_KEY

    public static final String HOST_KEY

See Also:
  Constant Field Values

#### PORT_KEY

    public static final String PORT_KEY

See Also:
  Constant Field Values

#### PATH_KEY

    public static final String PATH_KEY

See Also:
  Constant Field Values

#### QUERY_KEY

    public static final String QUERY_KEY

See Also:
  Constant Field Values

#### FRAGMENT_KEY

    public static final String FRAGMENT_KEY

See Also:
  Constant Field Values

#### CHARSET_KEY

    public static final String CHARSET_KEY

See Also:
  Constant Field Values

#### XHTML_MODE_KEY

    public static final String XHTML_MODE_KEY

See Also:
  Constant Field Values

#### scheme

    protected String scheme

#### user

    protected String user

#### host

    protected String host

#### port

    protected int port

#### path

    protected String path

#### query

    protected Map query

#### fragment

    protected String fragment

#### charset

    protected String charset

#### queryDelim

    protected String queryDelim

#### appendParams

    protected boolean appendParams

#### forceRelative

    protected boolean forceRelative

#### opaque

    protected boolean opaque

#### self

    protected final LinkTool self

### Constructor Detail

#### LinkTool

    public LinkTool()

Default constructor. Tool typically is configured before use.

### Method Detail

#### configure

    protected void configure(ValueParser props)

Configuration

Overrides:
  `configure` in class `SafeConfig`
Parameters:
  `props` - configuration values

#### duplicate

    protected LinkTool duplicate()

Equivalent to clone, but with no checked exceptions. If for some unfathomable reason clone() doesn't work, this will throw a RuntimeException.

Returns:
  new LinkTool

#### duplicate

    protected LinkTool duplicate(boolean deep)

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.

Parameters:
  `deep` - whether to make a deep copy
Returns:
  new LinkTool

#### setCharacterEncoding

    public void setCharacterEncoding(String chrst)

#### setXHTML

    public void setXHTML(boolean xhtml)

Controls the delimiter used for separating query data pairs. By default, the standard '&' character is used.

This is not exposed to templates as this decision is best not made at that level.

Subclasses may easily override the init() method to set this appropriately and then call super.init()

Parameters:
  `xhtml` - if true, the XHTML query data delimiter ('&amp;') will be used. if false, then '&' will be used.
See Also:
  Using Ampersands in Attribute Values (and Elsewhere)

#### setAppendParams

    public void setAppendParams(boolean addParams)

Sets whether or not the `setParam(java.lang.Object, java.lang.Object, boolean)` method will override existing query values for the same key or simply append the new value to a list of existing values.

Parameters:
  `addParams` - whether to add or replace params

#### setForceRelative

    public void setForceRelative(boolean forceRelative)

Sets whether or not the `createURI()` method should ignore the scheme, user, port and host values for non-opaque URIs, thus making `toString()` print the link as a relative one, not an absolute one. NOTE: using `absolute()`, `absolute(Object)`, `relative()`, or `relative(Object)` will alter this setting accordingly on the new instances they return.

Parameters:
  `forceRelative` - whether to force a relative URI

#### setScheme

    public void setScheme(Object obj)

This will treat empty strings like null values and will trim any trailing ':' character.

Parameters:
  `obj` - scheme

#### setUserInfo

    public void setUserInfo(Object obj)

Sets user info

Parameters:
  `obj` - user info

#### setHost

    public void setHost(Object obj)

Sets host

Parameters:
  `obj` - host

#### setPort

    public void setPort(Object obj)

If the specified object is null, this will set the port value to -1 to indicate that. If it is non-null and cannot be converted to an integer, then it will be set to -2 to indicate an error.

Parameters:
  `obj` - port

#### setPath

    public void setPath(Object obj)

If this instance is not opaque and the specified value does not start with a '/' character, then that will be prepended automatically.

Parameters:
  `obj` - path

#### appendPath

    public void appendPath(Object obj)

Uses `combinePath(java.lang.String, java.lang.String)` to add the specified value to the current `getPath()` value. If the specified value is null or this instance is opaque, then this is a no-op.

Parameters:
  `obj` - path

#### combinePath

    protected String combinePath(String start,
                                 String end)

If end is null, this will return start and vice versa. If neither is null, this will append the end to the start, making sure that there is only one '/' character between the two values.

Parameters:
  `start` - start path
  `end` - end path
Returns:
  combined path

#### setQuery

    public void setQuery(Object obj)

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.

Parameters:
  `obj` - query

#### normalizeQuery

    protected String normalizeQuery(String qs)

Parameters:
  `qs` - query string
Returns:
  normalized string

#### toQuery

    public String toQuery(Map parameters)

Converts the map of keys to values into a query string.

Parameters:
  `parameters` - parameters
Returns:
  query string

#### appendQuery

    public void appendQuery(Object obj)

Uses `combineQuery(java.lang.String, java.lang.String)` to append the specified value to the current `getQuery()` value.

Parameters:
  `obj` - query to append

#### setParam

    public void setParam(Object key,
                         Object value,
                         boolean append)

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.

Parameters:
  `key` - parameter key
  `value` - parameter value
  `append` - whether to append parameter to existing ones with same key

#### setParams

    public void setParams(Object obj,
                          boolean append)

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.

Parameters:
  `obj` - parameters
  `append` - whether to append parameters

#### removeParam

    public Object removeParam(Object key)

Removes the query pair(s) with the specified key from the query data and returns the remove value(s), if any.

Parameters:
  `key` - parameter key
Returns:
  parameter value or null

#### handleParamsBoolean

    protected void handleParamsBoolean(boolean keep)

In this class, this method ignores true values. If passed a false value, it will call `setQuery(java.lang.Object)` with a null value to clear all query data.

Parameters:
  `keep` - `false` will clear query

#### combineQuery

    protected String combineQuery(String current,
                                  String add)

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.

Parameters:
  `current` - current query
  `add` - added query
Returns:
  combined query

#### toQuery

    protected String toQuery(Object key,
                             Object value)

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.

Parameters:
  `key` - parameter key
  `value` - parameter value(s)
Returns:
  encoded query string fragment

#### appendAsArray

    protected void appendAsArray(StringBuilder out,
                                 Object key,
                                 Object[] arr)

#### parseQuery

    protected Map<String,Object> parseQuery(String query)

Uses `normalizeQuery(java.lang.String)` to make all delimiters in the specified query string match the current query delimiter and then uses `parseQuery(String,String)` to parse it according to that same delimiter.

Parameters:
  `query` - query string
Returns:
  parameters map

#### parseQuery

    protected Map<String,Object> parseQuery(String query,
                                            String queryDelim)

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.

Parameters:
  `query` - query string
  `queryDelim` - query delimiter
Returns:
  parameters map

#### setFragment

    public void setFragment(Object obj)

Sets the anchor for this instance and treats empty strings like null.

Parameters:
  `obj` - fragment

#### setFromURI

    protected boolean setFromURI(Object obj)

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.

Parameters:
  `obj` - URI
Returns:
  success

#### toURI

    protected URI toURI(Object obj)

Turns the specified object into a string and thereby a URI.

Parameters:
  `obj` - source object
Returns:
  URI or null

#### createURI

    protected URI createURI()

Tries to create a URI from the current port, opacity, scheme, userInfo, host, path, query and fragment set for this instance, using the `URI` constructor that is appropriate to the opacity.

Returns:
  URI object or null

#### getCharacterEncoding

    public String getCharacterEncoding()

Returns the configured charset used by the `encode(java.lang.Object)` and `decode(java.lang.Object)` methods.

Returns:
  character encoding

#### isXHTML

    public boolean isXHTML()

Returns true if the query delimiter used by this instance is using `&amp;` as the delimiter for query data pairs or just using `&`.

Returns:
  whether the query string delimiter uses the XHTML delimiter

#### getAppendParams

    public boolean getAppendParams()

Returns true if `param(Object,Object)` appends values; false if the method overwrites existing value(s) for the specified key.

Returns:
  whether parameters are appended to the query string

#### scheme

    public LinkTool scheme(Object scheme)

Returns a new instance with the specified value set as its scheme.

Parameters:
  `scheme` - scheme
Returns:
  new LinkTool

#### secure

    public LinkTool secure()

Returns a new instance with the scheme set to "https".

Returns:
  new LinkTool

#### insecure

    public LinkTool insecure()

Returns a new instance with the scheme set to "http".

Returns:
  new LinkTool

#### getScheme

    public String getScheme()

Return the scheme value for this instance.

Returns:
  scheme

#### isSecure

    public boolean isSecure()

Returns true if this instance's scheme is "https".

Returns:
  whether the protocol is secure

#### isOpaque

    public boolean isOpaque()

Returns true if this instance represents an opaque URI.

Returns:
  opacity flag
See Also:
  `URI`

#### user

    public LinkTool user(Object info)

Returns a new instance with the specified value set as its user info.

Parameters:
  `info` - user info
Returns:
  new LinkTool

#### getUser

    public String getUser()

Returns the `URI.getUserInfo()` value for this instance.

Returns:
  user info

#### host

    public LinkTool host(Object host)

Returns a new instance with the specified value set as its host. If no scheme has yet been set, the new instance will also have its scheme set to the `DEFAULT_SCHEME` (http).

Parameters:
  `host` - host
Returns:
  new LinkTool

#### getHost

    public String getHost()

Return the host value for this instance.

Returns:
  host

#### port

    public LinkTool port(Object 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.

Parameters:
  `port` - port
Returns:
  new LinkTool

#### getPort

    public Integer getPort()

Returns the port value, if any.

Returns:
  port or null

#### path

    public LinkTool path(Object pth)

Returns a new instance with the specified value set as its path.

Parameters:
  `pth` - path
Returns:
  new link tool

#### getPath

    public String getPath()

Returns the current path value for this instance.

Returns:
  path

#### append

    public LinkTool append(Object pth)

Appends the given value to the end of the current path value.

Parameters:
  `pth` - path to append
Returns:
  new LinkTool

#### getDirectory

    public String getDirectory()

Returns the directory stack in the set `getPath()` value, by just trimming off all that follows the last "/".

Returns:
  directory stack

#### getFile

    public String getFile()

Returns the last section of the path, which is all that follows the final "/".

Returns:
  file

#### getRoot

    public String 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.

Returns:
  root

#### root

    public LinkTool root()

Returns a new LinkTool instance that represents the "root" of the current one, if it has one. This essentially calls `absolute()` and sets the path, query, and fragment to null on the returned instance.

Returns:
  new LinkTool
See Also:
  `getRoot()`

#### directory

    public LinkTool directory()

Returns a new LinkTool instance with the path set to the result of `getDirectory()` and the query and fragment set to null.

Returns:
  new LinkTool

#### isRelative

    public boolean isRelative()

Returns true if this instance is being forced to return relative URIs or has a null scheme value.

Returns:
  whether the link is relative

#### relative

    public LinkTool relative()

Returns a copy of this LinkTool instance that has `setForceRelative(boolean)` set to true.

Returns:
  new LinkTool

#### relative

    public LinkTool relative(Object obj)

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.

Example: `<a href='$link.relative("/login/index.vm")'>Login Page</a>`
produces something like
`<a href="/myapp/login/index.vm">Login Page</a>`

Parameters:
  `obj` - A directory-relative URI reference (e.g. file path in current directory)
Returns:
  a new instance of LinkTool with the specified changes
See Also:
  `relative()`

#### getContextPath

    public String getContextPath()

At this level, this only returns the result of `getDirectory()`. It is here as an extension hook for subclasses to change the "context" for relative links.

Returns:
  context path
See Also:
  `relative(Object)`, `getDirectory()`

#### isAbsolute

    public boolean isAbsolute()

Returns true if this instance has a scheme value and is not being forced to create relative URIs.

Returns:
  whether this link is absolute

#### absolute

    public LinkTool absolute()

Returns a copy of this LinkTool instance that has `setForceRelative(boolean)` set to false and sets the scheme to the "http" if no scheme has been set yet.

Returns:
  new LinkTool

#### absolute

    public LinkTool absolute(Object obj)

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.

Example:
`<a href='$link.absolute("login/index.vm")'>Login Page</a>`
produces something like
`<a href="http://myserver.net/myapp/login/index.vm">Login Page</a>`;
`<a href='$link.absolute("/login/index.vm")'>Login Page</a>`
produces something like
`<a href="http://myserver.net/login/index.vm">Login Page</a>`;
and
`<a href='$link.absolute("http://theirserver.com/index.jsp")'>Their, Inc.</a>`
produces something like
`<a href="http://theirserver.net/index.jsp">Their, Inc.</a>`

Parameters:
  `obj` - A root-relative or context-relative path or an absolute URI.
Returns:
  a new instance of LinkTool with the specified path or URI
See Also:
  `absolute()`

#### uri

    public LinkTool uri(Object 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.

Parameters:
  `uri` - URI reference to set
Returns:
  a new instance of LinkTool

#### getUri

    public URI getUri()

If the tool is not in "safe mode"--which it is by default-- this will return the `URI` representation of this instance, if any.

Returns:
  URI
See Also:
  `SafeConfig.isSafeMode()`

#### getBaseRef

    public String 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">`

Returns:
  base link

#### query

    public LinkTool query(Object query)

Sets the specified value as the current query data, after normalizing the pair delimiters. This overrides any existing query.

Parameters:
  `query` - query string
Returns:
  new LinkTool

#### getQuery

    public String getQuery()

Returns the current query as a string, if any.

Returns:
  query string

#### param

    public LinkTool param(Object key,
                          Object value)

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.

Parameters:
  `key` - key of new query parameter
  `value` - value of new query parameter
Returns:
  a new instance of LinkTool

#### append

    public LinkTool append(Object key,
                           Object value)

Appends a new key=value pair to the existing query data.

Parameters:
  `key` - key of new query parameter
  `value` - value of new query parameter
Returns:
  a new instance of LinkTool

#### set

    public LinkTool set(Object key,
                        Object value)

Sets a new key=value pair to the existing query data, overwriting any previous pair(s) that have the same key.

Parameters:
  `key` - key of new query parameter
  `value` - value of new query parameter
Returns:
  a new instance of LinkTool

#### remove

    public LinkTool remove(Object key)

Returns a new LinkTool instance that has any value(s) under the specified key removed from the query data.

Parameters:
  `key` - key of the query pair(s) to be removed
Returns:
  a new instance of LinkTool

#### params

    public LinkTool params(Object parameters)

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.

Parameters:
  `parameters` - a boolean or new query data (either Map or query string)
Returns:
  a new instance of LinkTool

#### getParams

    public Map getParams()

#### anchor

    public LinkTool anchor(Object anchor)

Returns a copy of the link with the specified anchor to be added to the end of the generated hyperlink.

Example:
`<a href='$link.setAnchor("foo")'>Foo</a>`
produces something like
`<a href="#foo">Foo</a>`

Parameters:
  `anchor` - an internal document reference
Returns:
  a new instance of LinkTool with the set anchor

#### getAnchor

    public String getAnchor()

Returns the anchor (internal document reference) set for this link.

Returns:
  anchor

#### getSelf

    public LinkTool getSelf()

Returns:
  self

#### toString

    public String 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.

Overrides:
  `toString` in class `Object`
Returns:
  string representation

#### decodeQueryPercents

    protected String decodeQueryPercents(String url)

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.

Parameters:
  `url` - source url
Returns:
  decoded url

#### equals

    public boolean equals(Object obj)

This instance is considered equal to any LinkTool instance whose toString() method returns a String equal to that returned by this instance's toString()

Overrides:
  `equals` in class `Object`
Parameters:
  `obj` - object to compare to
Returns:
  equality
See Also:
  `toString()`

#### hashCode

    public int hashCode()

Returns the hash code for the result of toString(). If toString() returns `null` (yes, we do break that contract), this will return `-1`.

Overrides:
  `hashCode` in class `Object`
Returns:
  hash code

#### encode

    public String encode(Object obj)

Delegates encoding of the specified url content to `URLEncoder.encode(java.lang.String)` using the configured character encoding.

Parameters:
  `obj` - URL to encode
Returns:
  String - the encoded url.

#### decode

    public String decode(Object obj)

Delegates decoding of the specified url content to `URLDecoder.decode(java.lang.String)` using the configured character encoding.

Parameters:
  `obj` - URL to decode
Returns:
  String - the decoded url.