org.norther.tammi.spray.media.tool
Class LinkTool

java.lang.Object
  org.norther.tammi.core.pool.RecyclableSupport
      org.norther.tammi.core.pool.PoolableSupport
          org.norther.tammi.spray.engine.tool.GlobalTool
              org.norther.tammi.spray.engine.tool.ContextTool
                  org.norther.tammi.spray.media.tool.MediaTool
                      org.norther.tammi.spray.media.tool.LinkTool

All Implemented Interfaces:

Serializable, Cloneable, EventListener, Poolable, Recyclable, ContextBindingListener

Direct Known Subclasses:

TaskTool

public class LinkTool
extends MediaTool

A request context tool supporting creation of links to media filters.

Based on TemplateLink in the Apache Jakarta Turbine project.

Version:

$Id: LinkTool.java,v 1.60 2010-05-05 20:15:25 cvsimp Exp $

Author:

Dave Bryson, Jon S. Stevens, Ilkka Priha

See Also:

Serialized Form

Constructor Summary

LinkTool()
Constructs a new link.

Method Summary

LinkTool	addPathInfo(List<?> list) Adds a list of name=value pairs to the path info.
LinkTool	addPathInfo(String name, double value) Adds a name=value pair to the path info.
LinkTool	addPathInfo(String name, int value) Adds a name=value pair to the path info.
LinkTool	addPathInfo(String name, long value) Adds a name=value pair to the path info.
LinkTool	addPathInfo(String name, Object value) Adds a name=value pair to the path info.
LinkTool	addPathInfo(String name, String value) Adds a name=value pair to the path info.
LinkTool	addQueryString(List<?> list) Adds a list of name=value pairs to the query string.
LinkTool	addQueryString(String name) Adds a name to the query string.
LinkTool	addQueryString(String name, double value) Adds a name=value pair to the query string.
LinkTool	addQueryString(String name, int value) Adds a name=value pair to the query string.
LinkTool	addQueryString(String name, long value) Adds a name=value pair to the query string.
LinkTool	addQueryString(String name, Object value) Adds a name=value pair to the query string.
LinkTool	addQueryString(String name, String value) Adds a name=value pair to the query string.
boolean	checkPermission() Checks execute permission for the linked URL.
LinkTool	clear() Clears all current links.
LinkTool	clearBookmark() Clears the bookmark.
LinkTool	clearPathInfo() Clears the path info.
LinkTool	clearQueryString() Clears the query string.
Object	clone()
void	dispose() Disposes the object by setting its disposed flag.
protected String	encodePathInfo() Encodes the path info.
protected String	encodeQueryString() Encodes the query string.
boolean	exists() Checks whether the linked URL exists.
String	getBookmark() Gets the linked bookmark.
protected <F extends Filter> F	getFilter(Class<F> clazz) Gets the first specific filter from the filter chain.
String	getHost() Gets the linked host.
protected HostFilter<?>	getHostFilter() Gets the host filter from the filter stack.
String	getLink() Gets the linked link.
String	getLinkAnchor(String link) Gets the anchor of the specified link.
OrderedMap<String,String>	getLinkAnchors() Gets a map of link anchors for the current principal.
OrderedMap<String,String>	getLinkAnchors(boolean all) Gets a map of all link anchors.
String	getLinkBranch() Gets the branch key of link of the current request.
protected String	getLinked(String key) Gets the linked value.
protected LinkFilter<?>	getLinkFilter() Gets the link filter from the filter stack.
String	getLocale() Gets the linked locale.
String	getPathInfo() Gets the last component of the path info as a string.
String	getPipe() Gets the linked pipe.
String	getPipeAnchor(String pipe) Gets the anchor of the specified pipe.
OrderedMap<String,String>	getPipeAnchors() Gets a map of pipe anchors for the current principal.
OrderedMap<String,String>	getPipeAnchors(boolean all) Gets a map of all pipe anchors.
String	getPipeBranch() Gets the branch key of pipe of the current request.
protected PipeFilter<?>	getPipeFilter() Gets the pipe filter from the filter stack.
int	getPort() Gets the linked port.
String	getScheme() Gets the linked scheme.
String	getScriptName() Gets the linked script name (context path + servlet path).
String	getService() Gets the linked service.
String	getServiceAnchor(String service) Gets the anchor of the specified service.
OrderedMap<String,String>	getServiceAnchors() Gets a map of service anchors for the current principal.
OrderedMap<String,String>	getServiceAnchors(boolean all) Gets a map of all service anchors.
String	getServiceBranch() Gets the branch key of service of the current request.
protected ServiceFilter<?>	getServiceFilter() Gets the service filter from the filter stack.
String	getServletPath() Gets the linked servlet path.
String	getSource() Gets the linked cached source.
String	getTerminal() Gets the linked terminal.
String	getURL() Gets the URL as a string.
boolean	isAbsolute() Checks whether this link is absolute.
boolean	isEncoded() Checks whether this link is encoded.
protected boolean	isPathInfoParsed() Checks the parse path info option.
boolean	isRedirected() Checks whether this link is a redirection.
boolean	isSecure() Checks whether this link is secure.
protected void	linkModified() A callback informing subclasses about a modified link.
LinkTool	removeHost() Removes the linked host.
LinkTool	removeLink() Removes the linked link.
protected LinkTool	removeLinked(String key) Removes the linked value.
LinkTool	removePathInfo(String name) Removes a name=value pair from the path info.
LinkTool	removePipe() Removes the linked pipe.
LinkTool	removeQueryString(String name) Removes a name=value pair from the query string.
LinkTool	removeService() Removes the linked service.
LinkTool	reset() Resets the default URL.
LinkTool	resetHost() Resets the default host.
LinkTool	resetLink() Resets the default link.
LinkTool	resetPipe() Resets the default pipe.
LinkTool	resetService() Resets the default service.
LinkTool	setAbsolute(boolean flag) Sets this link to be either absolute or relative.
LinkTool	setAbsolute(Boolean flag) Sets this link to be either absolute, relative or keep it unchanged.
LinkTool	setBookmark(String bm) Sets the linked bookmark.
LinkTool	setEncoded(boolean flag) Sets this link to be encoded.
LinkTool	setEncoded(Boolean flag) Sets this link to be either encoded, decoded or keep it unchanged.
LinkTool	setHost(String host) Sets the linked host.
LinkTool	setLink(String link) Sets the linked link.
protected LinkTool	setLinked(String key, String value) Sets the linked value.
LinkTool	setLocale(String lang) Sets the linked locale.
LinkTool	setPathInfo(String info) Sets the last component of the path info as a string.
LinkTool	setPathInfo(String info, boolean always) Sets the last component of the path info as a string optionally only if the path info is not parsed.
LinkTool	setPipe(String pipe) Sets the linked pipe.
LinkTool	setPort(int port) Sets the linked port.
LinkTool	setRedirected(boolean flag) Sets this link to be a redirection.
LinkTool	setRedirected(Boolean flag) Sets this link to be either redirected, directed or keep it unchanged.
LinkTool	setScheme(String scheme) Sets the linked scheme.
LinkTool	setScriptName(String name) Sets the linked script name (context path + servlet path).
LinkTool	setSecure(boolean flag) Sets this link to be either secure or non-secure.
LinkTool	setSecure(boolean flag, int port) Sets this link to be either secure or non-secure and to use a given port.
LinkTool	setService(String service) Sets the linked service.
LinkTool	setServletPath(String path) Sets the linked servlet path.
LinkTool	setSource(String source) Sets the linked source.
LinkTool	setSource(String source, boolean localized) Sets the linked localized source.
LinkTool	setTerminal(String term) Sets the linked terminal.
LinkTool	setURL(String url) Sets the URL as a string.
String	toString() Returns the URL as a string and clears the link to its initial state.
LinkTool	use() Uses the current URL.
LinkTool	useTerminal() Uses the current terminal.
LinkTool	useUser() Uses the current user.

Methods inherited from class org.norther.tammi.spray.media.tool.MediaTool

toMediaFile, toURL, toURL

Methods inherited from class org.norther.tammi.spray.engine.tool.ContextTool

getFilterChain, getFilterKey, getPrincipal, getRequest, getResponse, isFilterChanged

Methods inherited from class org.norther.tammi.spray.engine.tool.GlobalTool

getContext, getContextToolFilter, getMBeanServer, isBound, nop, valueBound, valueUnbound

Methods inherited from class org.norther.tammi.core.pool.PoolableSupport

disposed, recycled

Methods inherited from class org.norther.tammi.core.pool.RecyclableSupport

isDisposed, recycle

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.norther.tammi.core.pool.Recyclable

isDisposed, recycle

Constructor Detail

LinkTool

public LinkTool()

Constructs a new link.

Method Detail

clone

public Object clone()

Overrides:

clone in class GlobalTool

dispose

public void dispose()

Description copied from class: RecyclableSupport

Disposes the object by setting its disposed flag.

Specified by:

dispose in interface Recyclable

Overrides:

dispose in class ContextTool

getScheme

public String getScheme()

Gets the linked scheme.

Returns:

the scheme or null.

setScheme

public LinkTool setScheme(String scheme)

Sets the linked scheme.

Parameters:

scheme - the scheme.

Returns:

the updated tool.

getPort

public int getPort()

Gets the linked port.

Returns:

the port or 0.

setPort

public LinkTool setPort(int port)

Sets the linked port.

Parameters:

port - the port.

Returns:

the updated tool.

getScriptName

public String getScriptName()

Gets the linked script name (context path + servlet path).

Note that the context path of the link URL can't be get or set alone but only as part of the script name.

Returns:

the script name or null.

setScriptName

public LinkTool setScriptName(String name)

Sets the linked script name (context path + servlet path).

Note that setting the servlet path has no effect after the script name has been set.

Parameters:

name - the script name.

Returns:

the updated tool.

getServletPath

public String getServletPath()

Gets the linked servlet path.

Returns:

the servlet path or null.

setServletPath

public LinkTool setServletPath(String path)

Sets the linked servlet path.

Note that setting the servlet path has no effect if the script name has already been set.

Parameters:

path - the servlet path.

Returns:

the updated tool.

isSecure

public boolean isSecure()

Checks whether this link is secure.

Returns:

true for a secure link, false otherwise.

setSecure

public LinkTool setSecure(boolean flag)

Sets this link to be either secure or non-secure. The scheme and server port are updated accordingly.

Parameters:

flag - true for a secure link, false otherwise.

Returns:

the updated tool.

setSecure

public LinkTool setSecure(boolean flag,
                          int port)

Sets this link to be either secure or non-secure and to use a given port. The scheme and server port are updated accordingly.

Parameters:

flag - true for a secure link, false otherwise.

port - the server port.

Returns:

the updated tool.

isAbsolute

public boolean isAbsolute()

Checks whether this link is absolute.

Returns:

true for an absolute link, false otherwise.

setAbsolute

public LinkTool setAbsolute(boolean flag)

Sets this link to be either absolute or relative. An absolute link contains the server name and port number.

Note that setting the flag to false does not supersede the AbsoluteURLLinks configuration option.

Parameters:

flag - the absolute flag.

Returns:

the updated tool.

setAbsolute

public LinkTool setAbsolute(Boolean flag)

Sets this link to be either absolute, relative or keep it unchanged.

Parameters:

flag - true for an absolute link, false for a non-secure one and null to keep unchanged.

Returns:

the updated tool.

isEncoded

public boolean isEncoded()

Checks whether this link is encoded.

Returns:

true for aencoded link, false otherwise.

setEncoded

public LinkTool setEncoded(boolean flag)

Sets this link to be encoded. An encoded link contains an encoded session id.

Parameters:

flag - the encoded flag.

Returns:

the updated tool.

setEncoded

public LinkTool setEncoded(Boolean flag)

Sets this link to be either encoded, decoded or keep it unchanged.

Parameters:

flag - true for an encoded link, false for a decoded one and null to keep unchanged.

Returns:

the updated tool.

isRedirected

public boolean isRedirected()

Checks whether this link is a redirection.

Returns:

true for a redirection link, false otherwise.

setRedirected

public LinkTool setRedirected(boolean flag)

Sets this link to be a redirection. A redirected link is always absolute and encoded with the HttpServletRequest.encodeRedirectURL method.

Parameters:

flag - the redirected flag.

Returns:

the updated tool.

setRedirected

public LinkTool setRedirected(Boolean flag)

Sets this link to be either redirected, directed or keep it unchanged.

Parameters:

flag - true for a redirected link, false for a directed one and null to keep unchanged.

Returns:

the updated tool.

getBookmark

public String getBookmark()

Gets the linked bookmark.

Returns:

the bookmark or null.

setBookmark

public LinkTool setBookmark(String bm)

Sets the linked bookmark.

Parameters:

bm - the bookmark.

Returns:

the updated tool.

clearBookmark

public LinkTool clearBookmark()

Clears the bookmark.

Returns:

the updated tool.

getPathInfo

public String getPathInfo()

Gets the last component of the path info as a string.

Returns:

info the absolute path info or null.

setPathInfo

public LinkTool setPathInfo(String info)

Sets the last component of the path info as a string.

Parameters:

info - the path info.

Returns:

the updated tool.

setPathInfo

public LinkTool setPathInfo(String info,
                            boolean always)

Sets the last component of the path info as a string optionally only if the path info is not parsed.

Parameters:

info - the path info.

always - the always option.

Returns:

the updated tool.

addPathInfo

public LinkTool addPathInfo(List<?> list)

Adds a list of name=value pairs to the path info. The name and the corresponding value must be subsequent items in the list.

Parameters:

list - the list.

Returns:

the updated tool.

addPathInfo

public LinkTool addPathInfo(String name,
                            Object value)

Adds a name=value pair to the path info.

Parameters:

name - the name.

value - the value.

Returns:

the updated tool

addPathInfo

public LinkTool addPathInfo(String name,
                            String value)

Adds a name=value pair to the path info.

Parameters:

name - the name.

value - the value.

Returns:

the updated tool.

Throws:

NullPointerException - for a null name.

IllegalArgumentException - for a name with slashes.

addPathInfo

public LinkTool addPathInfo(String name,
                            double value)

Adds a name=value pair to the path info.

Parameters:

name - the name.

value - the value.

Returns:

the updated tool.

addPathInfo

public LinkTool addPathInfo(String name,
                            int value)

Adds a name=value pair to the path info.

Parameters:

name - the name.

value - the value.

Returns:

the updated tool.

addPathInfo

public LinkTool addPathInfo(String name,
                            long value)

Adds a name=value pair to the path info.

Parameters:

name - the name.

value - the value.

Returns:

the updated tool.

removePathInfo

public LinkTool removePathInfo(String name)

Removes a name=value pair from the path info.

Note that possible dependencies are not updated, call dedicated remove methods when applicable.

Parameters:

name - the name to be removed.

Returns:

the updated tool.

clearPathInfo

public LinkTool clearPathInfo()

Clears the path info.

Returns:

the updated tool.

addQueryString

public LinkTool addQueryString(List<?> list)

Adds a list of name=value pairs to the query string. The name and the corresponding value must be subsequent items in the list.

Parameters:

list - the list.

Returns:

the updated tool.

addQueryString

public LinkTool addQueryString(String name)

Adds a name to the query string.

Parameters:

name - the name.

Returns:

the updated tool.

addQueryString

public LinkTool addQueryString(String name,
                               Object value)

Adds a name=value pair to the query string.

Parameters:

name - the name.

value - the value.

Returns:

the updated tool.

addQueryString

public LinkTool addQueryString(String name,
                               String value)

Adds a name=value pair to the query string.

Parameters:

name - the name.

value - the value.

Returns:

the updated tool.

Throws:

NullPointerException - for a null name.

addQueryString

public LinkTool addQueryString(String name,
                               double value)

Adds a name=value pair to the query string.

Parameters:

name - the name.

value - the value.

Returns:

the updated tool.

addQueryString

public LinkTool addQueryString(String name,
                               int value)

Adds a name=value pair to the query string.

Parameters:

name - the name.

value - the value.

Returns:

the updated tool.

addQueryString

public LinkTool addQueryString(String name,
                               long value)

Adds a name=value pair to the query string.

Parameters:

name - the name.

value - the value.

Returns:

the updated tool.

removeQueryString

public LinkTool removeQueryString(String name)

Removes a name=value pair from the query string.

Note that possible dependencies are not updated, call dedicated remove methods when applicable.

Parameters:

name - the name to be removed.

Returns:

the updated link.

clearQueryString

public LinkTool clearQueryString()

Clears the query string.

Returns:

the updated tool.

getHost

public String getHost()

Gets the linked host.

Returns:

the host or null.

resetHost

public LinkTool resetHost()

Resets the default host.

Returns:

the updated tool.

setHost

public LinkTool setHost(String host)

Sets the linked host.

Parameters:

host - the host.

Returns:

the updated tool.

removeHost

public LinkTool removeHost()

Removes the linked host.

Returns:

the updated tool.

resetService

public LinkTool resetService()

Resets the default service.

Returns:

the updated tool.

getService

public String getService()

Gets the linked service.

Returns:

the service or null.

setService

public LinkTool setService(String service)

Sets the linked service.

Parameters:

service - the service.

Returns:

the updated tool.

Throws:

NullPointerException - if not settable.

removeService

public LinkTool removeService()

Removes the linked service.

Returns:

the updated tool.

getServiceBranch

public String getServiceBranch()

Gets the branch key of service of the current request. If the branch doesn't have a link anchor, null is returned.

Returns:

the service branch or null.

getServiceAnchor

public String getServiceAnchor(String service)

Gets the anchor of the specified service.

Parameters:

service - the service.

Returns:

the anchor or null.

getServiceAnchors

public OrderedMap<String,String> getServiceAnchors()

Gets a map of service anchors for the current principal.

Returns:

a read-only map of service anchors.

getServiceAnchors

public OrderedMap<String,String> getServiceAnchors(boolean all)

Gets a map of all service anchors.

Parameters:

all - true for all links, false for authorized links.

Returns:

a read-only map of service anchors.

resetPipe

public LinkTool resetPipe()

Resets the default pipe.

Returns:

the updated tool.

getPipe

public String getPipe()

Gets the linked pipe.

Returns:

the pipe or null.

setPipe

public LinkTool setPipe(String pipe)

Sets the linked pipe.

Parameters:

pipe - the pipe.

Returns:

the updated tool.

Throws:

NullPointerException - if not settable.

removePipe

public LinkTool removePipe()

Removes the linked pipe.

Returns:

the updated tool.

getPipeBranch

public String getPipeBranch()

Gets the branch key of pipe of the current request. If the branch doesn't have a link anchor, null is returned.

Returns:

the pipe branch or null.

getPipeAnchor

public String getPipeAnchor(String pipe)

Gets the anchor of the specified pipe.

Parameters:

pipe - the pipe.

Returns:

the anchor or null.

getPipeAnchors

public OrderedMap<String,String> getPipeAnchors()

Gets a map of pipe anchors for the current principal.

Returns:

a read-only map of pipe anchors.

getPipeAnchors

public OrderedMap<String,String> getPipeAnchors(boolean all)

Gets a map of all pipe anchors.

Parameters:

all - true for all links, false for authorized links.

Returns:

a read-only map of pipe anchors.

resetLink

public LinkTool resetLink()

Resets the default link.

Returns:

the updated tool.

getLink

public String getLink()

Gets the linked link.

Returns:

the link or null.

setLink

public LinkTool setLink(String link)

Sets the linked link.

Parameters:

link - the link.

Returns:

the updated tool.

Throws:

NullPointerException - if not settable.

removeLink

public LinkTool removeLink()

Removes the linked link.

Returns:

the updated tool.

getLinkBranch

public String getLinkBranch()

Gets the branch key of link of the current request. If the branch doesn't have a link anchor, null is returned.

Returns:

the link branch or null.

getLinkAnchor

public String getLinkAnchor(String link)

Gets the anchor of the specified link.

Parameters:

link - the link.

Returns:

the anchor or null.

getLinkAnchors

public OrderedMap<String,String> getLinkAnchors()

Gets a map of link anchors for the current principal.

Returns:

a read-only map of link anchors.

getLinkAnchors

public OrderedMap<String,String> getLinkAnchors(boolean all)

Gets a map of all link anchors.

Parameters:

all - true for all links, false for authorized links.

Returns:

a read-only map of link anchors.

getLocale

public String getLocale()

Gets the linked locale.

Returns:

the locale or null.

setLocale

public LinkTool setLocale(String lang)

Sets the linked locale.

Parameters:

lang - the locale.

Returns:

the updated tool.

useTerminal

public LinkTool useTerminal()

Uses the current terminal.

Returns:

the updated tool.

getTerminal

public String getTerminal()

Gets the linked terminal.

Returns:

the terminal or null.

setTerminal

public LinkTool setTerminal(String term)

Sets the linked terminal.

Parameters:

term - the terminal.

Returns:

the updated tool.

getSource

public String getSource()

Gets the linked cached source.

Returns:

the cached source or null.

setSource

public LinkTool setSource(String source)

Sets the linked source.

Parameters:

source - the source.

Returns:

the updated tool.

setSource

public LinkTool setSource(String source,
                          boolean localized)

Sets the linked localized source.

Note that search for localized sources is available only if the content filter is configured to support localized content.

Parameters:

source - the source.

localized - true for a localized source.

Returns:

the updated tool.

useUser

public LinkTool useUser()

Uses the current user.

Returns:

the updated tool.

getURL

public String getURL()

Gets the URL as a string.

Note that the link is not XML encoded but the caller is responsible for pre- or post-processing the link for the target environment.

Returns:

the link URL.

reset

public LinkTool reset()

Resets the default URL.

Returns:

the updated tool.

use

public LinkTool use()

Uses the current URL.

Returns:

the updated tool.

setURL

public LinkTool setURL(String url)

Sets the URL as a string.

Note that the link may be a full or partial URL and the scheme, host, port and script name of the current link URL are updated accordingly. The path info and query string are cleared before setting the URL.

Parameters:

url - the link URL.

Returns:

the updated tool.

toString

public String toString()

Returns the URL as a string and clears the link to its initial state.

Note that the link is not XML encoded but the caller is responsible for pre- or post-processing the link for the target environment.

Overrides:

toString in class GlobalTool

Returns:

the link URL.

clear

public LinkTool clear()

Clears all current links.

Returns:

the cleared tool.

exists

public boolean exists()

Checks whether the linked URL exists.

Returns:

true or false.

checkPermission

public boolean checkPermission()

Checks execute permission for the linked URL.

Returns:

true or false.

linkModified

protected void linkModified()

A callback informing subclasses about a modified link.

getLinked

protected String getLinked(String key)

Gets the linked value.

Parameters:

key - the linked key.

Returns:

the linked value.

setLinked

protected LinkTool setLinked(String key,
                             String value)

Sets the linked value.

Parameters:

key - the linked key.

value - the linked value.

Returns:

the updated tool.

removeLinked

protected LinkTool removeLinked(String key)

Removes the linked value.

Parameters:

key - the linked key.

Returns:

the updated tool.

encodePathInfo

protected String encodePathInfo()

Encodes the path info.

Returns:

the absolute URL encoded path info or null.

encodeQueryString

protected String encodeQueryString()

Encodes the query string.

Returns:

the URL encoded query string or null.

isPathInfoParsed

protected boolean isPathInfoParsed()

Checks the parse path info option.

Returns:

true if path info is parsed.

getHostFilter

protected HostFilter<?> getHostFilter()

Gets the host filter from the filter stack.

Returns:

the host filter or null.

getServiceFilter

protected ServiceFilter<?> getServiceFilter()

Gets the service filter from the filter stack.

Returns:

the service filter or null.

getPipeFilter

protected PipeFilter<?> getPipeFilter()

Gets the pipe filter from the filter stack.

Returns:

the pipe filter or null.

getLinkFilter

protected LinkFilter<?> getLinkFilter()

Gets the link filter from the filter stack.

Returns:

the link filter or null.

getFilter

protected <F extends Filter> F getFilter(Class<F> clazz)

Description copied from class: ContextTool

Gets the first specific filter from the filter chain.

Overrides:

getFilter in class ContextTool

Type Parameters:

F - the filter type.

Parameters:

clazz - the class or interface of the filter.

Returns:

the found filter or null.