org.apache.velocity.tools.view

## Class LinkTool

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

All Implemented Interfaces:
  Serializable, Cloneable

    public class LinkTool
    extends LinkTool

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

- construct full URIs (absolute or relative)
- encode session ID into a URI
- retrieve server, port and path info for the current request
- reconstruct or alter the current request URI
- and more..

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.path('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.view.LinkTool"
                  forceRelative="true" includeRequestParams="true"/>
       </toolbox>
     </tools>

This tool may only be used in the request scope.

Since:
  VelocityTools 2.0
Version:
  $Id$
Author:
  Gabe Sidler, Nathan Bubna, Chris Schultz
See Also:
  Serialized Form

### Field Summary

Fields
`static String` `INCLUDE_REQUEST_PARAMS_KEY`
`protected boolean` `includeRequestParams`
`protected javax.servlet.http.HttpServletRequest` `request`
`protected javax.servlet.http.HttpServletResponse` `response`

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

`APPEND_PARAMS_KEY, appendParams, charset, CHARSET_KEY, DEFAULT_CHARSET, DEFAULT_SCHEME, FORCE_RELATIVE_KEY, forceRelative, fragment, FRAGMENT_KEY, host, HOST_KEY, HTML_QUERY_DELIMITER, opaque, path, PATH_KEY, port, PORT_KEY, query, QUERY_KEY, queryDelim, scheme, SCHEME_KEY, SECURE_SCHEME, self, URI_KEY, user, USER_KEY, XHTML_MODE_KEY, XHTML_QUERY_DELIMITER`

### 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()`

### Method Summary

All Methods Instance Methods Concrete Methods
`LinkTool` `addMissingRequestParams(Object... ignoreThese)` Adds all of the current request's parameters to this link's "query data" except for those whose keys match any of the specified strings or already have a value set for them in the current instance.
`LinkTool` `addRequestParams(Object... butOnlyThese)` Adds the specified parameters (if they exist) from the current request to the query data of a copy of this instance.
`LinkTool` `addRequestParamsExcept(Object... ignoreThese)` Adds all of the current request's parameters to this link's "query data" except for those whose keys match any of the specified strings.
`protected void` `configure(ValueParser props)`
`String` `getContextPath()` Initially, this returns the context path that addresses this web application, e.g.
`String` `getContextURL()` Returns a URL that addresses the web application.
`String` `getRequestPath()` Initially, this retrieves the path for the current request regardless of whether this is a direct request or an include by the RequestDispatcher.
`protected boolean` `isPathChanged()`
`protected void` `setFromRequest(javax.servlet.http.HttpServletRequest request)`
`void` `setIncludeRequestParams(boolean includeRequestParams)` Controls whether or not this tool starts off with all parameters from the last request automatically.
`String` `toString()` Overrides to use response.encodeURL to get session id into URL if sessions are used but cookies are not supported.

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

`absolute, absolute, anchor, append, append, appendAsArray, appendPath, appendQuery, combinePath, combineQuery, createURI, decode, decodeQueryPercents, directory, duplicate, duplicate, encode, equals, getAnchor, getAppendParams, getBaseRef, getCharacterEncoding, getDirectory, getFile, getHost, getParams, getPath, getPort, getQuery, getRoot, getScheme, getSelf, getUri, getUser, handleParamsBoolean, hashCode, host, insecure, isAbsolute, isOpaque, isRelative, isSecure, isXHTML, normalizeQuery, param, params, parseQuery, parseQuery, path, port, query, relative, relative, remove, removeParam, root, scheme, secure, set, setAppendParams, setCharacterEncoding, setForceRelative, setFragment, setFromURI, setHost, setParam, setParams, setPath, setPort, setQuery, setScheme, setUserInfo, setXHTML, toQuery, toQuery, toURI, uri, user`

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

#### INCLUDE_REQUEST_PARAMS_KEY

    public static final String INCLUDE_REQUEST_PARAMS_KEY

See Also:
  Constant Field Values

#### request

    protected javax.servlet.http.HttpServletRequest request

#### response

    protected javax.servlet.http.HttpServletResponse response

#### includeRequestParams

    protected boolean includeRequestParams

### Constructor Detail

#### LinkTool

    public LinkTool()

### Method Detail

#### configure

    protected void configure(ValueParser props)

Overrides:
  `configure` in class `LinkTool`

#### setFromRequest

    protected void setFromRequest(javax.servlet.http.HttpServletRequest request)

#### setIncludeRequestParams

    public void setIncludeRequestParams(boolean includeRequestParams)

Controls whether or not this tool starts off with all parameters from the last request automatically. Default is false.

Parameters:
  `includeRequestParams` - whether or not to keep current request params

#### addRequestParams

    public LinkTool addRequestParams(Object... butOnlyThese)

Adds the specified parameters (if they exist) from the current request to the query data of a copy of this instance. If no parameters are specified, then all of the current request's parameters will be added.

Parameters:
  `butOnlyThese` - curent request parameters to keep
Returns:
  A LinkTool object with the specified parameters from the current request added to it or all the params if none specified.

#### addRequestParamsExcept

    public LinkTool addRequestParamsExcept(Object... ignoreThese)

Adds all of the current request's parameters to this link's "query data" except for those whose keys match any of the specified strings.

Parameters:
  `ignoreThese` - curent request parameters to ignore
Returns:
  A LinkTool object with all of the current request's parameters added to it, except those specified.

#### addMissingRequestParams

    public LinkTool addMissingRequestParams(Object... ignoreThese)

Adds all of the current request's parameters to this link's "query data" except for those whose keys match any of the specified strings or already have a value set for them in the current instance.

Parameters:
  `ignoreThese` - curent request parameters to ignore
Returns:
  A LinkTool object with all of the current request's parameters added to it, except those specified or those that already have values.

#### isPathChanged

    protected boolean isPathChanged()

#### getContextPath

    public String getContextPath()

Initially, this returns the context path that addresses this web application, e.g. `/myapp`. This string starts with a "/" but does not end with a "/". If the path has been changed (e.g. via a call to `LinkTool.path(Object)`), then this will simply be the first "directory" in the path (i.e. everything from the start up to the second backslash).

Overrides:
  `getContextPath` in class `LinkTool`
Returns:
  context path
See Also:
  `LinkTool.relative(Object)`

#### getRequestPath

    public String getRequestPath()

Initially, this retrieves the path for the current request regardless of whether this is a direct request or an include by the RequestDispatcher. This string should always start with a "/". If the path has been changed (e.g. via a call to `LinkTool.path(Object)`), then this will simply be everything in the path after the `getContextPath()` (i.e. the second "/" in the path and everything after).

Returns:
  request path

#### getContextURL

    public String getContextURL()

Returns a URL that addresses the web application. (e.g. `http://myserver.net/myapp/`. This essentially just replaces the full path with the `getContextPath()` and removes the anchor and query data.

Returns:
  context URL

#### toString

    public String toString()

Overrides to use response.encodeURL to get session id into URL if sessions are used but cookies are not supported.

Overrides:
  `toString` in class `LinkTool`
Returns:
  final string representation