org.apache.velocity.tools.view.tools
Class LinkTool

java.lang.Object
  org.apache.velocity.tools.view.tools.LinkTool

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

SecureLinkTool, StrutsLinkTool

public class LinkTool
extends java.lang.Object
implements java.lang.Cloneable

View tool to make building URIs pleasant and fun!

 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:
 <tool>
   <key>link</key>
   <scope>request</scope>
   <class>org.apache.velocity.tools.view.tools.LinkTool</class>
 </tool>
 

This tool should only be used in the request scope.

Since:

VelocityTools 1.0

Version:

$Id: LinkTool.java 595062 2007-11-14 21:18:55Z nbubna $

Author:

Gabe Sidler, Nathan Bubna, Chris Schultz

Nested Class Summary

protected class

LinkTool.QueryPair Internal util class to handle representation and encoding of key/value pairs in the query string

Field Summary

private java.lang.String	anchor The anchor set for this link.
protected javax.servlet.ServletContext	application A reference to the ServletContext
static java.lang.String	AUTO_IGNORE_PARAMETERS_KEY Parameter key for configuring setAutoIgnoreParameters(boolean) state.
private boolean	autoIgnore true if parameters explicitly set on this LinkTool should be added to the ignore list.
private static java.lang.reflect.Method	encode Java 1.4 encode method to use instead of deprecated 1.3 version.
static java.lang.String	HTML_QUERY_DELIMITER Standard HTML delimiter for query data ('&')
protected static org.apache.commons.logging.Log	LOG
private java.util.HashSet	parametersToIgnore List of parameters that should be ignored when the current request's parameters are copied.
private java.util.ArrayList	queryData A list of query string parameters.
private java.lang.String	queryDataDelim The current delimiter for query data
protected javax.servlet.http.HttpServletRequest	request A reference to the HttpServletRequest.
protected javax.servlet.http.HttpServletResponse	response A reference to the HttpServletResponse.
static java.lang.String	SELF_ABSOLUTE_KEY Parameter key for configuring setSelfAbsolute(boolean) state
static java.lang.String	SELF_INCLUDE_PARAMETERS_KEY Parameter key for configuring setSelfIncludeParameters(boolean) state
private boolean	selfAbsolute The self-absolute status
private boolean	selfParams The self-include-parameters status
private java.lang.String	uri The URI reference set for this link.
static java.lang.String	XHTML_QUERY_DELIMITER XHTML delimiter for query data ('&')

Constructor Summary

LinkTool()
Default constructor.

Method Summary

LinkTool	absolute(java.lang.String uri) Convenience method equivalent to setAbsolute(java.lang.String).
LinkTool	addAllParameters() Adds all of the current request's parameters to this link's "query data".
LinkTool	addIgnore(java.lang.String parameterName) Instructs this LinkTool to ignore the specified parameter when copying the current request's parameters.
LinkTool	addQueryData(java.util.Map parameters) Adds multiple key=value pairs to the query data.
LinkTool	addQueryData(java.lang.String key, java.lang.Object value) Adds a key=value pair to the query data.
LinkTool	anchor(java.lang.String anchor) Convenience method equivalent to setAnchor(java.lang.String).
void	configure(java.util.Map params) Configures this tool
protected LinkTool	copyWith(LinkTool.QueryPair pair) For internal use.
protected LinkTool	copyWith(java.util.Map newQueryData) For internal use.
protected LinkTool	copyWith(java.lang.String uri) For internal use.
protected LinkTool	copyWithAnchor(java.lang.String anchor) For internal use.
protected LinkTool	copyWithIgnore(java.lang.String parameterName) For internal use.
protected LinkTool	duplicate() This is just to avoid duplicating this code for both copyWith() methods
java.lang.String	encodeURL(java.lang.String url) Use the new URLEncoder.encode() method from java 1.4 if available, else use the old deprecated version.
java.lang.String	getAnchor() Returns the anchor (internal document reference) set for this link.
java.lang.String	getBaseRef() Returns the full URI of this template without any query data.
java.lang.String	getContextPath() Returns the context path that addresses this web application, e.g.
java.lang.String	getContextURL() Returns the URI that addresses this web application.
java.lang.String	getParams() Convenience method equivalent to getQueryData().
java.lang.String	getQueryData() Returns this link's query data as a url-encoded string e.g.
java.lang.String	getRequestPath() Retrieves the path for the current request regardless of whether this is a direct request or an include by the RequestDispatcher.
LinkTool	getSelf() This method returns a new "self-referencing" LinkTool for the current request.
java.lang.String	getUri() Convenience method equivalent to getURI() to enable all lowercase $link.uri syntax.
java.lang.String	getURI() Returns the current URI of this link as set by the setURI(String), setAbsolute(String) or setRelative(String) methods.
void	init(java.lang.Object obj) Initializes this tool.
LinkTool	param(java.lang.Object key, java.lang.Object value) Convenience method equivalent to addQueryData(java.lang.String, java.lang.Object).
LinkTool	params(java.util.Map parameters) Convenience method equivalent to addQueryData(Map parameters).
LinkTool	relative(java.lang.String uri) Convenience method equivalent to setRelative(java.lang.String).
LinkTool	setAbsolute(java.lang.String uri) Returns a copy of the link with the specified URI reference either used as or converted to an absolute (non-relative) URI reference.
LinkTool	setAnchor(java.lang.String anchor) Returns a copy of the link with the specified anchor to be added to the end of the generated hyperlink.
protected void	setAutoIgnoreParameters(boolean autoIgnore) Controls whether or not the addQueryData(String,Object) and addQueryData(Map) methods will automatically add the specified parameter(s) to the ignore list for addAllParameters()
LinkTool	setRelative(java.lang.String uri) Returns a copy of the link with the specified context-relative URI reference converted to a server-relative URI reference.
protected void	setSelfAbsolute(boolean selfAbsolute) Controls whether or not the getSelf() method will return a duplicate with a URI in absolute or relative form.
protected void	setSelfIncludeParameters(boolean selfParams) Controls whether or not the getSelf() method will return a duplicate that includes current request parameters.
LinkTool	setURI(java.lang.String uri) Returns a copy of the link with the given URI reference set.
protected void	setXhtml(boolean useXhtml) Controls the delimiter used for separating query data pairs.
java.lang.String	toString() Returns the full URI reference that's been built with this tool, including the query string and anchor, e.g.
LinkTool	uri(java.lang.String uri) Convenience method equivalent to setURI(java.lang.String).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

LOG

protected static final org.apache.commons.logging.Log LOG

SELF_ABSOLUTE_KEY

public static final java.lang.String SELF_ABSOLUTE_KEY

Parameter key for configuring setSelfAbsolute(boolean) state

Since:

VelocityTools 1.3

See Also:

Constant Field Values

SELF_INCLUDE_PARAMETERS_KEY

public static final java.lang.String SELF_INCLUDE_PARAMETERS_KEY

Parameter key for configuring setSelfIncludeParameters(boolean) state

Since:

VelocityTools 1.3

See Also:

Constant Field Values

AUTO_IGNORE_PARAMETERS_KEY

public static final java.lang.String AUTO_IGNORE_PARAMETERS_KEY

Parameter key for configuring setAutoIgnoreParameters(boolean) state.

Since:

VelocityTools 1.4

See Also:

Constant Field Values

HTML_QUERY_DELIMITER

public static final java.lang.String HTML_QUERY_DELIMITER

Standard HTML delimiter for query data ('&')

See Also:

Constant Field Values

XHTML_QUERY_DELIMITER

public static final java.lang.String XHTML_QUERY_DELIMITER

XHTML delimiter for query data ('&')

See Also:

Constant Field Values

application

protected javax.servlet.ServletContext application

A reference to the ServletContext

request

protected javax.servlet.http.HttpServletRequest request

A reference to the HttpServletRequest.

response

protected javax.servlet.http.HttpServletResponse response

A reference to the HttpServletResponse.

uri

private java.lang.String uri

The URI reference set for this link.

anchor

private java.lang.String anchor

The anchor set for this link.

queryData

private java.util.ArrayList queryData

A list of query string parameters.

queryDataDelim

private java.lang.String queryDataDelim

The current delimiter for query data

selfAbsolute

private boolean selfAbsolute

The self-absolute status

selfParams

private boolean selfParams

The self-include-parameters status

parametersToIgnore

private java.util.HashSet parametersToIgnore

List of parameters that should be ignored when the current request's parameters are copied.

See Also:

addIgnore(String), addAllParameters()

autoIgnore

private boolean autoIgnore

true if parameters explicitly set on this LinkTool should be added to the ignore list.

See Also:

parametersToIgnore

encode

private static java.lang.reflect.Method encode

Java 1.4 encode method to use instead of deprecated 1.3 version.

Constructor Detail

LinkTool

public LinkTool()

Default constructor. Tool must be initialized before use.

Method Detail

setXhtml

protected void setXhtml(boolean useXhtml)

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:

useXhtml - if true, the XHTML query data delimiter ('&') will be used. if false, then '&' will be used.

See Also:

Using Ampersands in Attribute Values (and Elsewhere)

setSelfAbsolute

protected void setSelfAbsolute(boolean selfAbsolute)

Controls whether or not the getSelf() method will return a duplicate with a URI in absolute or relative form.

Parameters:

selfAbsolute - if true, the getSelf() method will return a duplicate of this tool with an absolute self-referencing URI; if false, a duplicate with a relative self-referencing URI will be returned

Since:

VelocityTools 1.3

See Also:

getSelf()

setSelfIncludeParameters

protected void setSelfIncludeParameters(boolean selfParams)

Controls whether or not the getSelf() method will return a duplicate that includes current request parameters.

Parameters:

selfParams - if true, the getSelf() method will return a duplicate of this tool that includes current request parameters

Since:

VelocityTools 1.3

See Also:

getSelf()

setAutoIgnoreParameters

protected void setAutoIgnoreParameters(boolean autoIgnore)

Controls whether or not the addQueryData(String,Object) and addQueryData(Map) methods will automatically add the specified parameter(s) to the ignore list for addAllParameters()

The default for this setting is true.

Parameters:

autoIgnore - if true, the addQueryData(String,Object) and addQueryData(Map) methods will automatically add the specified parameter(s) to the ignore list for addAllParameters(); otherwise, addIgnore(String) must be called explicitly for each parameter to ignore.

Since:

VelocityTools 1.4

See Also:

addIgnore(String), addAllParameters()

copyWith

protected LinkTool copyWith(LinkTool.QueryPair pair)

For internal use. Copies 'that' LinkTool into this one and adds the new query data.

Parameters:

pair - the query parameter to add

copyWith

protected LinkTool copyWith(java.util.Map newQueryData)

For internal use. Copies 'that' LinkTool into this one and adds the new query data.

Parameters:

newQueryData - the query parameters to add

Since:

VelocityTools 1.3

copyWith

protected LinkTool copyWith(java.lang.String uri)

For internal use. Copies 'that' LinkTool into this one and sets the new URI.

Parameters:

uri - uri string

copyWithAnchor

protected LinkTool copyWithAnchor(java.lang.String anchor)

For internal use. Copies 'that' LinkTool into this one and sets the new anchor for the link.

Parameters:

anchor - URI string

copyWithIgnore

protected LinkTool copyWithIgnore(java.lang.String parameterName)

For internal use. Copies this LinkTool and adds the specified parameter name to the ignore list in the copy.

Parameters:

parameterName - The name of the parameter to ignore when copying all parameters from the current request.

Returns:

A new LinkTool with the specified parameterName added to the ignore list.

See Also:

addAllParameters(), addIgnore(String)

duplicate

protected LinkTool duplicate()

This is just to avoid duplicating this code for both copyWith() methods

configure

public void configure(java.util.Map params)

Configures this tool

Parameters:

params - Map of configuration parameters

Since:

VelocityTools 1.3

init

public void init(java.lang.Object obj)

Initializes this tool.

Parameters:

obj - the current ViewContext

Throws:

java.lang.IllegalArgumentException - if the param is not a ViewContext

setAnchor

public LinkTool setAnchor(java.lang.String 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

anchor

public LinkTool anchor(java.lang.String anchor)

Convenience method equivalent to setAnchor(java.lang.String).

Since:

VelocityTools 1.3

getAnchor

public java.lang.String getAnchor()

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

setRelative

public LinkTool setRelative(java.lang.String uri)

Returns a copy of the link with the specified context-relative URI reference converted to a server-relative URI reference. This method will overwrite any previous URI reference settings but will copy the query string.

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

Parameters:

uri - A context-relative URI reference. A context-relative URI is a URI that is relative to the root of this web application.

Returns:

a new instance of LinkTool with the specified URI

relative

public LinkTool relative(java.lang.String uri)

Convenience method equivalent to setRelative(java.lang.String).

Since:

VelocityTools 1.3

setAbsolute

public LinkTool setAbsolute(java.lang.String uri)

Returns a copy of the link with the specified URI reference either used as or converted to an absolute (non-relative) URI reference. This method will overwrite any previous URI reference settings but will copy the query string.

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

Parameters:

uri - A context-relative URI reference or absolute URL.

Returns:

a new instance of LinkTool with the specified URI

Since:

VelocityTools 1.3

absolute

public LinkTool absolute(java.lang.String uri)

Convenience method equivalent to setAbsolute(java.lang.String).

Since:

VelocityTools 1.3

setURI

public LinkTool setURI(java.lang.String uri)

Returns a copy of the link with the given URI reference set. No conversions 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 any previous URI reference settings but will copy the query string.

Parameters:

uri - URI reference to set

Returns:

a new instance of LinkTool

uri

public LinkTool uri(java.lang.String uri)

Convenience method equivalent to setURI(java.lang.String).

Since:

VelocityTools 1.3

getURI

public java.lang.String getURI()

Returns the current URI of this link as set by the setURI(String), setAbsolute(String) or setRelative(String) methods. Any conversions have been applied. The returned URI reference does not include query data that was added with method addQueryData().

getUri

public java.lang.String getUri()

Convenience method equivalent to getURI() to enable all lowercase $link.uri syntax.

Since:

VelocityTools 1.3

addQueryData

public LinkTool addQueryData(java.lang.String key,
                             java.lang.Object value)

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. Query data is URL encoded before it is appended.

Parameters:

key - key of new query parameter

value - value of new query parameter

Returns:

a new instance of LinkTool

addQueryData

public LinkTool addQueryData(java.util.Map parameters)

Adds multiple key=value pairs to the query data. This returns a new LinkTool containing both a copy of this LinkTool's query data and the new data. Query data is URL encoded before it is appended.

Parameters:

parameters - map of new query data keys to values

Returns:

a new instance of LinkTool

Since:

VelocityTools 1.3

param

public LinkTool param(java.lang.Object key,
                      java.lang.Object value)

Convenience method equivalent to addQueryData(java.lang.String, java.lang.Object).

Since:

VelocityTools 1.3

params

public LinkTool params(java.util.Map parameters)

Convenience method equivalent to addQueryData(Map parameters).

Since:

VelocityTools 1.3

getQueryData

public java.lang.String getQueryData()

Returns this link's query data as a url-encoded string e.g. key=value&foo=this+is+encoded.

getParams

public java.lang.String getParams()

Convenience method equivalent to getQueryData().

Since:

VelocityTools 1.3

getContextURL

public java.lang.String getContextURL()

Returns the URI that addresses this web application. E.g. http://myserver.net/myapp. This string does not end with a "/". Note! This will not represent any URI reference or query data set for this LinkTool.

getContextPath

public java.lang.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 any URI reference or query data set for this LinkTool.

getRequestPath

public java.lang.String getRequestPath()

Retrieves the path for the current request regardless of whether this is a direct request or an include by the RequestDispatcher. Note! This will not represent any URI reference or query data set for this LinkTool.

Since:

VelocityTools 1.3

getBaseRef

public java.lang.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">

getSelf

public LinkTool getSelf()

This method returns a new "self-referencing" LinkTool for the current request. By default, this is merely a shortcut for calling relative(String uri) using the result of getRequestPath(). However, this tool can be configured to return an absolute URI and/or to include the parameters of the current request (in addition to any others set so far).

Since:

VelocityTools 1.3

See Also:

uri(String uri), configure(Map params), setSelfAbsolute(boolean selfAbsolute), setSelfIncludeParameters(boolean selfParams), addAllParameters()

toString

public java.lang.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 java.lang.Object

encodeURL

public java.lang.String encodeURL(java.lang.String url)

Use the new URLEncoder.encode() method from java 1.4 if available, else use the old deprecated version. This method uses reflection to find the appropriate method; if the reflection operations throw exceptions, this will return the url encoded with the old URLEncoder.encode() method.

Returns:

String - the encoded url.

addIgnore

public LinkTool addIgnore(java.lang.String parameterName)

Instructs this LinkTool to ignore the specified parameter when copying the current request's parameters.

Parameters:

parameterName - The name of the parameter to ignore.

See Also:

addAllParameters()

addAllParameters

public LinkTool addAllParameters()

Adds all of the current request's parameters to this link's "query data". Any parameters that have been set to be ignored will be ignored.

Returns:

A LinkTool object with all of the current request's parameters added to it.

See Also:

addIgnore(String)