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

java.lang.Object
  |
  +--org.apache.velocity.tools.view.tools.LinkTool

All Implemented Interfaces:

java.lang.Cloneable, ViewTool

Direct Known Subclasses:

StrutsLinkTool

public class LinkTool

extends java.lang.Object

implements ViewTool, java.lang.Cloneable

View tool to make building URIs pleasant and fun! :)

This class is equipped to be used with a toolbox manager, for example the ServletToolboxManager included with VelocityViewServlet. This class implements interface ViewTool, which allows a toolbox manager to pass the required context information.

This class is not thread-safe by design. A new instance is needed for the processing of every template request. This means this tool should only be used in the request scope, not application or session scopes.

Version:

$Id: LinkTool.java,v 1.7 2003/05/28 00:17:16 nbubna Exp $

Author:

Gabe Sidler, Nathan Bubna

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
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 ('&')
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.
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	addQueryData(java.lang.String key, java.lang.Object value) Adds a key=value pair to the query data.
protected LinkTool	copyWith(LinkTool.QueryPair pair) For internal use.
protected LinkTool	copyWith(java.lang.String uri) For internal use.
protected LinkTool	copyWithAnchor(java.lang.String anchor) For internal use.
private LinkTool	duplicate() This is just to avoid duplicating this code for both copyWith() methods
static 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	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	getQueryData() Returns this link's query data as a url-encoded string e.g.
java.lang.String	getURI() Returns the current URI of this link as set by the setURI(String) or setRelative(String) methods.
void	init(java.lang.Object obj) Initializes this tool.
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.
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.
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.

Methods inherited from class java.lang.Object

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

Field Detail

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

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)

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

duplicate

private LinkTool duplicate()

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

init

public void init(java.lang.Object obj)

Initializes this tool.

Specified by:

init in interface ViewTool

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

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

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

getURI

public java.lang.String getURI()

Returns the current URI of this link as set by the setURI(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().

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

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.

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.

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

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 static 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.