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

java.lang.Object
  extended by 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 ('&amp;')
 
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 ('&amp;')

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 ('&amp;') 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)


Copyright (c) 2003-2007 Apache Software Foundation