Class LinkTool
- java.lang.Object
-
- org.apache.velocity.tools.generic.SafeConfig
-
- org.apache.velocity.tools.generic.LinkTool
-
- All Implemented Interfaces:
java.lang.Cloneable
- Direct Known Subclasses:
LinkTool
@DefaultKey("link") @SkipSetters @ValidScope("request") public class LinkTool extends SafeConfig implements java.lang.Cloneable
The LinkTool provides many methods to work with URIs and can help you:
- construct full URIs (opaque, absolute or relative)
- encode and decode URLs (part or whole)
- retrieve path info for the current request
- and more..
This GenericTools (i.e. non-servlet based) version of LinkTool is largely based upon the same API and behavior as the older VelocityView version, with a few differences, particularly in internal representation and query handling. You can expect that in the future work will be done to more closely align the APIs. It is likely that the VelocityView version will become a subclass of this version that adds on servlet-awareness and related features. For now, though, they are entirely separate but similar tools.
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.relative('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.generic.LinkTool" uri="http://velocity.apache.org/tools/devel/"/> </toolbox> </tools>
- Since:
- VelocityTools 2.0
- Version:
- $Id: LinkTool.java 601976 2007-12-07 03:50:51Z nbubna $
- Author:
- Nathan Bubna
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
APPEND_PARAMS_KEY
protected boolean
appendParams
protected java.lang.String
charset
static java.lang.String
CHARSET_KEY
static java.lang.String
DEFAULT_CHARSET
static java.lang.String
DEFAULT_SCHEME
static java.lang.String
FORCE_RELATIVE_KEY
protected boolean
forceRelative
protected java.lang.String
fragment
static java.lang.String
FRAGMENT_KEY
protected java.lang.String
host
static java.lang.String
HOST_KEY
static java.lang.String
HTML_QUERY_DELIMITER
Standard HTML delimiter for query data ('&')protected org.apache.velocity.runtime.log.Log
LOG
protected boolean
opaque
protected java.lang.String
path
static java.lang.String
PATH_KEY
protected int
port
static java.lang.String
PORT_KEY
protected java.util.Map
query
static java.lang.String
QUERY_KEY
protected java.lang.String
queryDelim
protected java.lang.String
scheme
static java.lang.String
SCHEME_KEY
static java.lang.String
SECURE_SCHEME
protected LinkTool
self
static java.lang.String
URI_KEY
protected java.lang.String
user
static java.lang.String
USER_KEY
static java.lang.String
XHTML_MODE_KEY
static java.lang.String
XHTML_QUERY_DELIMITER
XHTML delimiter for query data ('&')-
Fields inherited from class org.apache.velocity.tools.generic.SafeConfig
LOCK_CONFIG_KEY, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY
-
-
Constructor Summary
Constructors Constructor Description LinkTool()
Default constructor.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description LinkTool
absolute()
Returns a copy of this LinkTool instance that hassetForceRelative(boolean)
set to false and sets the scheme to the "http" if no scheme has been set yet.LinkTool
absolute(java.lang.Object obj)
Returns a copy of the link with the specified URI reference either used as or converted to an absolute (non-relative) URI reference.private void
addToList(java.util.List vals, java.lang.Object value)
LinkTool
anchor(java.lang.Object anchor)
Returns a copy of the link with the specified anchor to be added to the end of the generated hyperlink.LinkTool
append(java.lang.Object pth)
Appends the given value to the end of the current path value.LinkTool
append(java.lang.Object key, java.lang.Object value)
Appends a new key=value pair to the existing query data.protected void
appendAsArray(java.lang.StringBuilder out, java.lang.Object key, java.lang.Object[] arr)
private void
appendParam(java.lang.String key, java.lang.Object value)
void
appendPath(java.lang.Object obj)
UsescombinePath(java.lang.String, java.lang.String)
to add the specified value to the currentgetPath()
value.void
appendQuery(java.lang.Object obj)
UsescombineQuery(java.lang.String, java.lang.String)
to append the specified value to the currentgetQuery()
value.protected java.lang.String
combinePath(java.lang.String start, java.lang.String end)
If end is null, this will return start and vice versa.protected java.lang.String
combineQuery(java.lang.String current, java.lang.String add)
If the second param is null or empty, this will simply return the first and vice versa.protected void
configure(ValueParser props)
Does the actual configuration.protected java.net.URI
createURI()
Tries to create a URI from the current port, opacity, scheme, userInfo, host, path, query and fragment set for this instance, using theURI
constructor that is appropriate to the opacity.protected void
debug(java.lang.String msg, java.lang.Object... args)
protected void
debug(java.lang.String msg, java.lang.Throwable t, java.lang.Object... args)
java.lang.String
decode(java.lang.Object obj)
Delegates decoding of the specified url content toURLDecoder.decode(java.lang.String)
using the configured character encoding.protected java.lang.String
decodeQueryPercents(java.lang.String url)
This is an ugly (but fast) hack that's needed because URI encodes things that we don't need encoded while not encoding things that we do need encoded.LinkTool
directory()
Returns a new LinkTool instance with the path set to the result ofgetDirectory()
and the query and fragment set to null.protected LinkTool
duplicate()
Equivalent to clone, but with no checked exceptions.protected LinkTool
duplicate(boolean deep)
Equivalent to clone, but with no checked exceptions.java.lang.String
encode(java.lang.Object obj)
Delegates encoding of the specified url content toURLEncoder.encode(java.lang.String)
using the configured character encoding.boolean
equals(java.lang.Object obj)
This instance is considered equal to any LinkTool instance whose toString() method returns a String equal to that returned by this instance's toString()java.lang.String
getAnchor()
Returns the anchor (internal document reference) set for this link.boolean
getAppendParams()
Returns true ifparam(Object,Object)
appends values; false if the method overwrites existing value(s) for the specified key.java.lang.String
getBaseRef()
Returns the full URI of this template without any query data.java.lang.String
getCharacterEncoding()
Returns the configured charset used by theencode(java.lang.Object)
anddecode(java.lang.Object)
methods.java.lang.String
getContextPath()
At this level, this only returns the result ofgetDirectory()
.java.lang.String
getDirectory()
Returns the directory stack in the setgetPath()
value, by just trimming off all that follows the last "/".java.lang.String
getFile()
Returns the last section of the path, which is all that follows the final "/".java.lang.String
getHost()
Return the host value for this instance.java.util.Map
getParams()
java.lang.String
getPath()
Returns the current path value for this instance.java.lang.Integer
getPort()
Returns the port value, if any.java.lang.String
getQuery()
Returns the current query as a string, if any.java.lang.String
getRoot()
Returns the "root" for this URI, if it has one.java.lang.String
getScheme()
Return the scheme value for this instance.LinkTool
getSelf()
java.net.URI
getUri()
If the tool is not in "safe mode"--which it is by default-- this will return theURI
representation of this instance, if any.java.lang.String
getUser()
Returns theURI.getUserInfo()
value for this instance.protected void
handleParamsBoolean(boolean keep)
In this class, this method ignores true values.int
hashCode()
Returns the hash code for the result of toString().LinkTool
host(java.lang.Object host)
Returns a new instance with the specified value set as its host.LinkTool
insecure()
Returns a new instance with the scheme set to "http".boolean
isAbsolute()
Returns true if this instance has a scheme value and is not being forced to create relative URIs.boolean
isOpaque()
Returns true if this instance represents an opaque URI.boolean
isRelative()
Returns true if this instance is being forced to return relative URIs or has a null scheme value.boolean
isSecure()
Returns true if this instance's scheme is "https".boolean
isXHTML()
Returns true if the query delimiter used by this instance is using&
as the delimiter for query data pairs or just using&
.protected java.lang.String
normalizeQuery(java.lang.String qs)
LinkTool
param(java.lang.Object key, java.lang.Object value)
Adds a key=value pair to the query data.LinkTool
params(java.lang.Object parameters)
This method can do two different things.protected java.util.Map<java.lang.String,java.lang.Object>
parseQuery(java.lang.String query)
UsesnormalizeQuery(java.lang.String)
to make all delimiters in the specified query string match the current query delimiter and then usesparseQuery(String,String)
to parse it according to that same delimiter.protected java.util.Map<java.lang.String,java.lang.Object>
parseQuery(java.lang.String query, java.lang.String queryDelim)
This will use the specified query delimiter to parse the specified query string into a map of keys to values.LinkTool
path(java.lang.Object pth)
Returns a new instance with the specified value set as its path.LinkTool
port(java.lang.Object port)
Returns a new instance with the specified value set as its port number.private void
putParam(java.lang.Object key, java.lang.Object value)
LinkTool
query(java.lang.Object query)
Sets the specified value as the current query data, after normalizing the pair delimiters.LinkTool
relative()
Returns a copy of this LinkTool instance that hassetForceRelative(boolean)
set to true.LinkTool
relative(java.lang.Object obj)
Returns a copy of the link with the specified directory-relative URI reference set as the end of the path andsetForceRelative(boolean)
set to true.LinkTool
remove(java.lang.Object key)
Returns a new LinkTool instance that has any value(s) under the specified key removed from the query data.java.lang.Object
removeParam(java.lang.Object key)
Removes the query pair(s) with the specified key from the query data and returns the remove value(s), if any.LinkTool
root()
Returns a new LinkTool instance that represents the "root" of the current one, if it has one.LinkTool
scheme(java.lang.Object scheme)
Returns a new instance with the specified value set as its scheme.LinkTool
secure()
Returns a new instance with the scheme set to "https".LinkTool
set(java.lang.Object key, java.lang.Object value)
Sets a new key=value pair to the existing query data, overwriting any previous pair(s) that have the same key.void
setAppendParams(boolean addParams)
Sets whether or not thesetParam(java.lang.Object, java.lang.Object, boolean)
method will override existing query values for the same key or simply append the new value to a list of existing values.void
setCharacterEncoding(java.lang.String chrst)
void
setForceRelative(boolean forceRelative)
Sets whether or not thecreateURI()
method should ignore the scheme, user, port and host values for non-opaque URIs, thus makingtoString()
print the link as a relative one, not an absolute one.void
setFragment(java.lang.Object obj)
Sets the anchor for this instance and treats empty strings like null.protected boolean
setFromURI(java.lang.Object obj)
If the specified value is null, this will set the scheme, userInfo, host, port, path, query, and fragment all to their null-equivalent values.void
setHost(java.lang.Object obj)
void
setParam(java.lang.Object key, java.lang.Object value, boolean append)
If there is no existing value for this key in the query, it will simply add it and its value to the query.void
setParams(java.lang.Object obj, boolean append)
If append is false, this simply delegates tosetQuery(java.lang.Object)
.void
setPath(java.lang.Object obj)
If this instance is not opaque and the specified value does not start with a '/' character, then that will be prepended automatically.void
setPort(java.lang.Object obj)
If the specified object is null, this will set the port value to -1 to indicate that.void
setQuery(java.lang.Object obj)
If the specified value is null, it will set the query to null.void
setScheme(java.lang.Object obj)
This will treat empty strings like null values and will trim any trailing ':' character.void
setUserInfo(java.lang.Object obj)
void
setXHTML(boolean xhtml)
Controls the delimiter used for separating query data pairs.protected java.lang.String
toQuery(java.lang.Object key, java.lang.Object value)
Turns the specified key and value into a properly encoded query pair string.java.lang.String
toQuery(java.util.Map parameters)
Converts the map of keys to values into a query string.java.lang.String
toString()
Returns the full URI reference that's been built with this tool, including the query string and anchor, e.g.protected java.net.URI
toURI(java.lang.Object obj)
Turns the specified object into a string and thereby a URI.LinkTool
uri(java.lang.Object uri)
Returns a copy of the link with the given URI reference set.LinkTool
user(java.lang.Object info)
Returns a new instance with the specified value set as its user info.-
Methods inherited from class org.apache.velocity.tools.generic.SafeConfig
configure, isConfigLocked, isSafeMode, setLockConfig, setSafeMode
-
-
-
-
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
-
APPEND_PARAMS_KEY
public static final java.lang.String APPEND_PARAMS_KEY
- See Also:
- Constant Field Values
-
FORCE_RELATIVE_KEY
public static final java.lang.String FORCE_RELATIVE_KEY
- See Also:
- Constant Field Values
-
DEFAULT_CHARSET
public static final java.lang.String DEFAULT_CHARSET
- See Also:
- Constant Field Values
-
DEFAULT_SCHEME
public static final java.lang.String DEFAULT_SCHEME
- See Also:
- Constant Field Values
-
SECURE_SCHEME
public static final java.lang.String SECURE_SCHEME
- See Also:
- Constant Field Values
-
URI_KEY
public static final java.lang.String URI_KEY
- See Also:
- Constant Field Values
-
SCHEME_KEY
public static final java.lang.String SCHEME_KEY
- See Also:
- Constant Field Values
-
USER_KEY
public static final java.lang.String USER_KEY
- See Also:
- Constant Field Values
-
HOST_KEY
public static final java.lang.String HOST_KEY
- See Also:
- Constant Field Values
-
PORT_KEY
public static final java.lang.String PORT_KEY
- See Also:
- Constant Field Values
-
PATH_KEY
public static final java.lang.String PATH_KEY
- See Also:
- Constant Field Values
-
QUERY_KEY
public static final java.lang.String QUERY_KEY
- See Also:
- Constant Field Values
-
FRAGMENT_KEY
public static final java.lang.String FRAGMENT_KEY
- See Also:
- Constant Field Values
-
CHARSET_KEY
public static final java.lang.String CHARSET_KEY
- See Also:
- Constant Field Values
-
XHTML_MODE_KEY
public static final java.lang.String XHTML_MODE_KEY
- See Also:
- Constant Field Values
-
LOG
protected org.apache.velocity.runtime.log.Log LOG
-
scheme
protected java.lang.String scheme
-
user
protected java.lang.String user
-
host
protected java.lang.String host
-
port
protected int port
-
path
protected java.lang.String path
-
query
protected java.util.Map query
-
fragment
protected java.lang.String fragment
-
charset
protected java.lang.String charset
-
queryDelim
protected java.lang.String queryDelim
-
appendParams
protected boolean appendParams
-
forceRelative
protected boolean forceRelative
-
opaque
protected boolean opaque
-
self
protected final LinkTool self
-
-
Method Detail
-
debug
protected final void debug(java.lang.String msg, java.lang.Object... args)
-
debug
protected final void debug(java.lang.String msg, java.lang.Throwable t, java.lang.Object... args)
-
configure
protected void configure(ValueParser props)
Description copied from class:SafeConfig
Does the actual configuration. This is protected, so subclasses may share the same ValueParser and call configure at any time, while preventing templates from doing so when configure(Map) is locked.- Overrides:
configure
in classSafeConfig
-
duplicate
protected LinkTool duplicate()
Equivalent to clone, but with no checked exceptions. If for some unfathomable reason clone() doesn't work, this will throw a RuntimeException.
-
duplicate
protected LinkTool duplicate(boolean deep)
Equivalent to clone, but with no checked exceptions. If for some unfathomable reason clone() doesn't work, this will throw a RuntimeException. If doing a deep clone, then the parameter Map will also be cloned.
-
setCharacterEncoding
public void setCharacterEncoding(java.lang.String chrst)
-
setXHTML
public void setXHTML(boolean xhtml)
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:
xhtml
- 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)
-
setAppendParams
public void setAppendParams(boolean addParams)
Sets whether or not thesetParam(java.lang.Object, java.lang.Object, boolean)
method will override existing query values for the same key or simply append the new value to a list of existing values.
-
setForceRelative
public void setForceRelative(boolean forceRelative)
Sets whether or not thecreateURI()
method should ignore the scheme, user, port and host values for non-opaque URIs, thus makingtoString()
print the link as a relative one, not an absolute one. NOTE: usingabsolute()
,absolute(Object)
,relative()
, orrelative(Object)
will alter this setting accordingly on the new instances they return.
-
setScheme
public void setScheme(java.lang.Object obj)
This will treat empty strings like null values and will trim any trailing ':' character.
-
setUserInfo
public void setUserInfo(java.lang.Object obj)
-
setHost
public void setHost(java.lang.Object obj)
-
setPort
public void setPort(java.lang.Object obj)
If the specified object is null, this will set the port value to -1 to indicate that. If it is non-null and cannot be converted to an integer, then it will be set to -2 to indicate an error.
-
setPath
public void setPath(java.lang.Object obj)
If this instance is not opaque and the specified value does not start with a '/' character, then that will be prepended automatically.
-
appendPath
public void appendPath(java.lang.Object obj)
UsescombinePath(java.lang.String, java.lang.String)
to add the specified value to the currentgetPath()
value. If the specified value is null or this instance is opaque, then this is a no-op.
-
combinePath
protected java.lang.String combinePath(java.lang.String start, java.lang.String end)
If end is null, this will return start and vice versa. If neither is null, this will append the end to the start, making sure that there is only one '/' character between the two values.
-
setQuery
public void setQuery(java.lang.Object obj)
If the specified value is null, it will set the query to null. If a Map, it will copy all those values into a new LinkedHashMap and replace any current query value with that. If it is a String, it will useparseQuery(String)
to parse it into a map of keys to values.
-
normalizeQuery
protected java.lang.String normalizeQuery(java.lang.String qs)
-
toQuery
public java.lang.String toQuery(java.util.Map parameters)
Converts the map of keys to values into a query string.
-
appendQuery
public void appendQuery(java.lang.Object obj)
UsescombineQuery(java.lang.String, java.lang.String)
to append the specified value to the currentgetQuery()
value.
-
setParam
public void setParam(java.lang.Object key, java.lang.Object value, boolean append)
If there is no existing value for this key in the query, it will simply add it and its value to the query. If the key already is present in the query and append is true, this will add the specified value to those already under that key. IfappendParams
is false, this will override the existing values with the specified new value.
-
appendParam
private void appendParam(java.lang.String key, java.lang.Object value)
-
putParam
private void putParam(java.lang.Object key, java.lang.Object value)
-
addToList
private void addToList(java.util.List vals, java.lang.Object value)
-
setParams
public void setParams(java.lang.Object obj, boolean append)
If append is false, this simply delegates tosetQuery(java.lang.Object)
. Otherwise, if the specified object is null, it does nothing. If the object is not a Map, it will turn it into a String and useparseQuery(java.lang.String)
to parse it. Once it is a Map, it will iterate through the entries appending each key/value to the current query data.
-
removeParam
public java.lang.Object removeParam(java.lang.Object key)
Removes the query pair(s) with the specified key from the query data and returns the remove value(s), if any.
-
handleParamsBoolean
protected void handleParamsBoolean(boolean keep)
In this class, this method ignores true values. If passed a false value, it will callsetQuery(java.lang.Object)
with a null value to clear all query data.
-
combineQuery
protected java.lang.String combineQuery(java.lang.String current, java.lang.String add)
If the second param is null or empty, this will simply return the first and vice versa. Otherwise, it will trim any '?' at the start of the second param and any '&' or '&' at the end of the first one, then combine the two, making sure that they are separated by only one delimiter.
-
toQuery
protected java.lang.String toQuery(java.lang.Object key, java.lang.Object value)
Turns the specified key and value into a properly encoded query pair string. If the value is an array or List, then this will create a delimited string of query pairs, reusing the same key for each of the values separately.
-
appendAsArray
protected void appendAsArray(java.lang.StringBuilder out, java.lang.Object key, java.lang.Object[] arr)
-
parseQuery
protected java.util.Map<java.lang.String,java.lang.Object> parseQuery(java.lang.String query)
UsesnormalizeQuery(java.lang.String)
to make all delimiters in the specified query string match the current query delimiter and then usesparseQuery(String,String)
to parse it according to that same delimiter.
-
parseQuery
protected java.util.Map<java.lang.String,java.lang.Object> parseQuery(java.lang.String query, java.lang.String queryDelim)
This will use the specified query delimiter to parse the specified query string into a map of keys to values. If there are multiple query pairs in the string that have the same key, then the values will be combined into a single List value associated with that key.
-
setFragment
public void setFragment(java.lang.Object obj)
Sets the anchor for this instance and treats empty strings like null.
-
setFromURI
protected boolean setFromURI(java.lang.Object obj)
If the specified value is null, this will set the scheme, userInfo, host, port, path, query, and fragment all to their null-equivalent values. Otherwise, this will convert the specified object into aURI
, then those same values from the URI object to this instance.
-
toURI
protected java.net.URI toURI(java.lang.Object obj)
Turns the specified object into a string and thereby a URI.
-
createURI
protected java.net.URI createURI()
Tries to create a URI from the current port, opacity, scheme, userInfo, host, path, query and fragment set for this instance, using theURI
constructor that is appropriate to the opacity.
-
getCharacterEncoding
public java.lang.String getCharacterEncoding()
Returns the configured charset used by theencode(java.lang.Object)
anddecode(java.lang.Object)
methods.
-
isXHTML
public boolean isXHTML()
Returns true if the query delimiter used by this instance is using&
as the delimiter for query data pairs or just using&
.
-
getAppendParams
public boolean getAppendParams()
Returns true ifparam(Object,Object)
appends values; false if the method overwrites existing value(s) for the specified key.
-
scheme
public LinkTool scheme(java.lang.Object scheme)
Returns a new instance with the specified value set as its scheme.
-
secure
public LinkTool secure()
Returns a new instance with the scheme set to "https".
-
insecure
public LinkTool insecure()
Returns a new instance with the scheme set to "http".
-
getScheme
public java.lang.String getScheme()
Return the scheme value for this instance.
-
isSecure
public boolean isSecure()
Returns true if this instance's scheme is "https".
-
isOpaque
public boolean isOpaque()
Returns true if this instance represents an opaque URI.- See Also:
URI
-
user
public LinkTool user(java.lang.Object info)
Returns a new instance with the specified value set as its user info.
-
getUser
public java.lang.String getUser()
Returns theURI.getUserInfo()
value for this instance.
-
host
public LinkTool host(java.lang.Object host)
Returns a new instance with the specified value set as its host. If no scheme has yet been set, the new instance will also have its scheme set to theDEFAULT_SCHEME
(http).
-
getHost
public java.lang.String getHost()
Return the host value for this instance.
-
port
public LinkTool port(java.lang.Object port)
Returns a new instance with the specified value set as its port number. If the value cannot be parsed into an integer, the returned instance will always return null fortoString()
and othercreateURI()
-dependent methods to alert the user to the error.
-
getPort
public java.lang.Integer getPort()
Returns the port value, if any.
-
path
public LinkTool path(java.lang.Object pth)
Returns a new instance with the specified value set as its path.
-
getPath
public java.lang.String getPath()
Returns the current path value for this instance.
-
append
public LinkTool append(java.lang.Object pth)
Appends the given value to the end of the current path value.
-
getDirectory
public java.lang.String getDirectory()
Returns the directory stack in the setgetPath()
value, by just trimming off all that follows the last "/".
-
getFile
public java.lang.String getFile()
Returns the last section of the path, which is all that follows the final "/".
-
getRoot
public java.lang.String getRoot()
Returns the "root" for this URI, if it has one. This does not stick close to URI dogma and will try to insert the default scheme if there is none, and will return null if there is no host or if there was an error when the port value was last set. It will return null for any opaque URLs as well, as those have no host or port.
-
root
public LinkTool root()
Returns a new LinkTool instance that represents the "root" of the current one, if it has one. This essentially callsabsolute()
and sets the path, query, and fragment to null on the returned instance.- See Also:
getRoot()
-
directory
public LinkTool directory()
Returns a new LinkTool instance with the path set to the result ofgetDirectory()
and the query and fragment set to null.
-
isRelative
public boolean isRelative()
Returns true if this instance is being forced to return relative URIs or has a null scheme value.
-
relative
public LinkTool relative()
Returns a copy of this LinkTool instance that hassetForceRelative(boolean)
set to true.
-
relative
public LinkTool relative(java.lang.Object obj)
Returns a copy of the link with the specified directory-relative URI reference set as the end of the path and
Example:setForceRelative(boolean)
set to true. If the specified relative path is null, that is treated the same as an empty path.
<a href='$link.relative("/login/index.vm")'>Login Page</a>
produces something like<a href="/myapp/login/index.vm">Login Page</a>
- Parameters:
obj
- A directory-relative URI reference (e.g. file path in current directory)- Returns:
- a new instance of LinkTool with the specified changes
- See Also:
relative()
-
getContextPath
public java.lang.String getContextPath()
At this level, this only returns the result ofgetDirectory()
. It is here as an extension hook for subclasses to change the "context" for relative links.- See Also:
relative(Object)
,getDirectory()
-
isAbsolute
public boolean isAbsolute()
Returns true if this instance has a scheme value and is not being forced to create relative URIs.
-
absolute
public LinkTool absolute()
Returns a copy of this LinkTool instance that hassetForceRelative(boolean)
set to false and sets the scheme to the "http" if no scheme has been set yet.
-
absolute
public LinkTool absolute(java.lang.Object obj)
Returns a copy of the link with the specified URI reference either used as or converted to an absolute (non-relative) URI reference. Unless the specified URI contains a query or anchor, those values will not be overwritten when using this method.
Example:
<a href='$link.absolute("login/index.vm")'>Login Page</a>
produces something like
<a href="http://myserver.net/myapp/login/index.vm">Login Page</a>
;
<a href='$link.absolute("/login/index.vm")'>Login Page</a>
produces something like
<a href="http://myserver.net/login/index.vm">Login Page</a>
;
and
<a href='$link.absolute("http://theirserver.com/index.jsp")'>Their, Inc.</a>
produces something like
<a href="http://theirserver.net/index.jsp">Their, Inc.</a>
- Parameters:
obj
- A root-relative or context-relative path or an absolute URI.- Returns:
- a new instance of LinkTool with the specified path or URI
- See Also:
absolute()
-
uri
public LinkTool uri(java.lang.Object uri)
Returns a copy of the link with the given URI reference set. Few changes 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 all previous settings for scheme, host port, path, query and anchor.
- Parameters:
uri
- URI reference to set- Returns:
- a new instance of LinkTool
-
getUri
public java.net.URI getUri()
If the tool is not in "safe mode"--which it is by default-- this will return theURI
representation of this instance, if any.- See Also:
SafeConfig.isSafeMode()
-
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">
-
query
public LinkTool query(java.lang.Object query)
Sets the specified value as the current query data, after normalizing the pair delimiters. This overrides any existing query.
-
getQuery
public java.lang.String getQuery()
Returns the current query as a string, if any.
-
param
public LinkTool param(java.lang.Object key, java.lang.Object value)
Adds a key=value pair to the query data. Whether this new query pair is appended to the current query or overwrites any previous pair(s) with the same key is controlled by the
getAppendParams()
value. The default behavior is to append.- Parameters:
key
- key of new query parametervalue
- value of new query parameter- Returns:
- a new instance of LinkTool
-
append
public LinkTool append(java.lang.Object key, java.lang.Object value)
Appends a new key=value pair to the existing query data.- Parameters:
key
- key of new query parametervalue
- value of new query parameter- Returns:
- a new instance of LinkTool
-
set
public LinkTool set(java.lang.Object key, java.lang.Object value)
Sets a new key=value pair to the existing query data, overwriting any previous pair(s) that have the same key.- Parameters:
key
- key of new query parametervalue
- value of new query parameter- Returns:
- a new instance of LinkTool
-
remove
public LinkTool remove(java.lang.Object key)
Returns a new LinkTool instance that has any value(s) under the specified key removed from the query data.- Parameters:
key
- key of the query pair(s) to be removed- Returns:
- a new instance of LinkTool
-
params
public LinkTool params(java.lang.Object parameters)
This method can do two different things. If you pass in a boolean, it will create a new LinkTool duplicate and callhandleParamsBoolean(boolean)
on it. In this class, true values do nothing (subclasses may have use for them), but false values will clear out all params in the query for that instance. If you pass in a query string or a Map of parameters, those values will be added to the new LinkTool, either overwriting previous value(s) with those keys or appending to them, depending on thegetAppendParams()
value.- Parameters:
parameters
- a boolean or new query data (either Map or query string)- Returns:
- a new instance of LinkTool
-
getParams
public java.util.Map getParams()
-
anchor
public LinkTool anchor(java.lang.Object 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
-
getAnchor
public java.lang.String getAnchor()
Returns the anchor (internal document reference) set for this link.
-
getSelf
public LinkTool getSelf()
-
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 classjava.lang.Object
-
decodeQueryPercents
protected java.lang.String decodeQueryPercents(java.lang.String url)
This is an ugly (but fast) hack that's needed because URI encodes things that we don't need encoded while not encoding things that we do need encoded. So, we have to encode query data before creating the URI to ensure they are properly encoded, but then URI encodes all the % from that encoding. Here, we isolate the query data and manually decode the encoded %25 in that section back to %, without decoding anything else.
-
equals
public boolean equals(java.lang.Object obj)
This instance is considered equal to any LinkTool instance whose toString() method returns a String equal to that returned by this instance's toString()- Overrides:
equals
in classjava.lang.Object
- See Also:
toString()
-
hashCode
public int hashCode()
Returns the hash code for the result of toString(). If toString() returnsnull
(yes, we do break that contract), this will return-1
.- Overrides:
hashCode
in classjava.lang.Object
-
encode
public java.lang.String encode(java.lang.Object obj)
Delegates encoding of the specified url content toURLEncoder.encode(java.lang.String)
using the configured character encoding.- Returns:
- String - the encoded url.
-
decode
public java.lang.String decode(java.lang.Object obj)
Delegates decoding of the specified url content toURLDecoder.decode(java.lang.String)
using the configured character encoding.- Returns:
- String - the decoded url.
-
-