|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.apache.velocity.tools.generic.SafeConfig org.apache.velocity.tools.generic.LinkTool
@DefaultKey(value="link") @SkipSetters @ValidScope(value="request") public class LinkTool
The LinkTool provides many methods to work with URIs and can help you:
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>
Field Summary | |
---|---|
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 | |
---|---|
LinkTool()
Default constructor. |
Method Summary | |
---|---|
LinkTool |
absolute()
Returns a copy of this LinkTool instance that has setForceRelative(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)
Uses combinePath(java.lang.String, java.lang.String) to add the specified value
to the current getPath() value. |
void |
appendQuery(java.lang.Object obj)
Uses combineQuery(java.lang.String, java.lang.String) to append the specified value
to the current getQuery() 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 the URI 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 to URLDecoder.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 of getDirectory()
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 to URLEncoder.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 if param(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 the encode(java.lang.Object) and
decode(java.lang.Object) methods. |
java.lang.String |
getContextPath()
At this level, this only returns the result of getDirectory() . |
java.lang.String |
getDirectory()
Returns the directory stack in the set getPath() 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 the URI representation of this instance,
if any. |
java.lang.String |
getUser()
Returns the URI.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)
Uses normalizeQuery(java.lang.String) to make all delimiters in the
specified query string match the current query delimiter
and then uses parseQuery(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 has setForceRelative(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 and setForceRelative(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 the setParam(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 the createURI() method should ignore the
scheme, user, port and host values for non-opaque URIs, thus making
toString() 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 to setQuery(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. |
java.lang.String |
toQuery(java.util.Map parameters)
Converts the map of keys to values into a query string. |
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 |
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 |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String HTML_QUERY_DELIMITER
public static final java.lang.String XHTML_QUERY_DELIMITER
public static final java.lang.String APPEND_PARAMS_KEY
public static final java.lang.String FORCE_RELATIVE_KEY
public static final java.lang.String DEFAULT_CHARSET
public static final java.lang.String DEFAULT_SCHEME
public static final java.lang.String SECURE_SCHEME
public static final java.lang.String URI_KEY
public static final java.lang.String SCHEME_KEY
public static final java.lang.String USER_KEY
public static final java.lang.String HOST_KEY
public static final java.lang.String PORT_KEY
public static final java.lang.String PATH_KEY
public static final java.lang.String QUERY_KEY
public static final java.lang.String FRAGMENT_KEY
public static final java.lang.String CHARSET_KEY
public static final java.lang.String XHTML_MODE_KEY
protected org.apache.velocity.runtime.log.Log LOG
protected java.lang.String scheme
protected java.lang.String user
protected java.lang.String host
protected int port
protected java.lang.String path
protected java.util.Map query
protected java.lang.String fragment
protected java.lang.String charset
protected java.lang.String queryDelim
protected boolean appendParams
protected boolean forceRelative
protected boolean opaque
protected final LinkTool self
Constructor Detail |
---|
public LinkTool()
Method Detail |
---|
protected final void debug(java.lang.String msg, java.lang.Object... args)
protected final void debug(java.lang.String msg, java.lang.Throwable t, java.lang.Object... args)
protected void configure(ValueParser props)
SafeConfig
configure
in class SafeConfig
protected LinkTool duplicate()
protected LinkTool duplicate(boolean deep)
public void setCharacterEncoding(java.lang.String chrst)
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()
xhtml
- if true, the XHTML query data delimiter ('&')
will be used. if false, then '&' will be used.public void setAppendParams(boolean addParams)
setParam(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.
public void setForceRelative(boolean forceRelative)
createURI()
method should ignore the
scheme, user, port and host values for non-opaque URIs, thus making
toString()
print the link as a relative one, not an absolute
one. NOTE: using absolute()
, absolute(Object)
,
relative()
, or relative(Object)
will alter this
setting accordingly on the new instances they return.
public void setScheme(java.lang.Object obj)
public void setUserInfo(java.lang.Object obj)
public void setHost(java.lang.Object obj)
public void setPort(java.lang.Object obj)
public void setPath(java.lang.Object obj)
public void appendPath(java.lang.Object obj)
combinePath(java.lang.String, java.lang.String)
to add the specified value
to the current getPath()
value. If the specified
value is null or this instance is opaque, then this is
a no-op.
protected java.lang.String combinePath(java.lang.String start, java.lang.String end)
public void setQuery(java.lang.Object obj)
parseQuery(String)
to parse it into a map
of keys to values.
protected java.lang.String normalizeQuery(java.lang.String qs)
public java.lang.String toQuery(java.util.Map parameters)
public void appendQuery(java.lang.Object obj)
combineQuery(java.lang.String, java.lang.String)
to append the specified value
to the current getQuery()
value.
public void setParam(java.lang.Object key, java.lang.Object value, boolean append)
appendParams
is
false, this will override the existing values with the
specified new value.
private void appendParam(java.lang.String key, java.lang.Object value)
private void putParam(java.lang.Object key, java.lang.Object value)
private void addToList(java.util.List vals, java.lang.Object value)
public void setParams(java.lang.Object obj, boolean append)
setQuery(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 use parseQuery(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.
public java.lang.Object removeParam(java.lang.Object key)
protected void handleParamsBoolean(boolean keep)
setQuery(java.lang.Object)
with a null value to clear all query data.
protected java.lang.String combineQuery(java.lang.String current, java.lang.String add)
protected java.lang.String toQuery(java.lang.Object key, java.lang.Object value)
protected void appendAsArray(java.lang.StringBuilder out, java.lang.Object key, java.lang.Object[] arr)
protected java.util.Map<java.lang.String,java.lang.Object> parseQuery(java.lang.String query)
normalizeQuery(java.lang.String)
to make all delimiters in the
specified query string match the current query delimiter
and then uses parseQuery(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)
public void setFragment(java.lang.Object obj)
protected boolean setFromURI(java.lang.Object obj)
URI
, then those same
values from the URI object to this instance.
protected java.net.URI toURI(java.lang.Object obj)
protected java.net.URI createURI()
URI
constructor that is appropriate to the opacity.
public java.lang.String getCharacterEncoding()
encode(java.lang.Object)
and
decode(java.lang.Object)
methods.
public boolean isXHTML()
&
as the delimiter for query data pairs
or just using &
.
public boolean getAppendParams()
param(Object,Object)
appends values;
false if the method overwrites existing value(s) for the specified key.
public LinkTool scheme(java.lang.Object scheme)
public LinkTool secure()
public LinkTool insecure()
public java.lang.String getScheme()
public boolean isSecure()
public boolean isOpaque()
URI
public LinkTool user(java.lang.Object info)
public java.lang.String getUser()
URI.getUserInfo()
value for this instance.
public LinkTool host(java.lang.Object host)
DEFAULT_SCHEME
(http).
public java.lang.String getHost()
public LinkTool port(java.lang.Object port)
toString()
and other
createURI()
-dependent methods to alert the user
to the error.
public java.lang.Integer getPort()
public LinkTool path(java.lang.Object pth)
public java.lang.String getPath()
public LinkTool append(java.lang.Object pth)
public java.lang.String getDirectory()
getPath()
value, by just trimming
off all that follows the last "/".
public java.lang.String getFile()
public java.lang.String getRoot()
public LinkTool root()
absolute()
and
sets the path, query, and fragment to null on
the returned instance.
getRoot()
public LinkTool directory()
getDirectory()
and the query and fragment set to null.
public boolean isRelative()
public LinkTool relative()
setForceRelative(boolean)
set to true.
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 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>
<a href="/myapp/login/index.vm">Login Page</a>
obj
- A directory-relative URI reference (e.g. file path in current directory)
relative()
public java.lang.String getContextPath()
getDirectory()
.
It is here as an extension hook for subclasses to change the
"context" for relative links.
relative(Object)
,
getDirectory()
public boolean isAbsolute()
public LinkTool absolute()
setForceRelative(boolean)
set to false and sets the
scheme to the "http" if no scheme has been set yet.
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>
<a href="http://myserver.net/myapp/login/index.vm">Login Page</a>
;<a href='$link.absolute("/login/index.vm")'>Login Page</a>
<a href="http://myserver.net/login/index.vm">Login Page</a>
;<a href='$link.absolute("http://theirserver.com/index.jsp")'>Their, Inc.</a>
<a href="http://theirserver.net/index.jsp">Their, Inc.</a>
obj
- A root-relative or context-relative path or an absolute URI.
absolute()
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.
uri
- URI reference to set
public java.net.URI getUri()
URI
representation of this instance,
if any.
SafeConfig.isSafeMode()
public java.lang.String getBaseRef()
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">
public LinkTool query(java.lang.Object query)
public java.lang.String getQuery()
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.
key
- key of new query parametervalue
- value of new query parameter
public LinkTool append(java.lang.Object key, java.lang.Object value)
key
- key of new query parametervalue
- value of new query parameter
public LinkTool set(java.lang.Object key, java.lang.Object value)
key
- key of new query parametervalue
- value of new query parameter
public LinkTool remove(java.lang.Object key)
key
- key of the query pair(s) to be removed
public LinkTool params(java.lang.Object parameters)
handleParamsBoolean(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 the getAppendParams()
value.
parameters
- a boolean or new query data (either Map or query string)
public java.util.Map getParams()
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>
<a href="#foo">Foo</a>
anchor
- an internal document reference
public java.lang.String getAnchor()
public LinkTool getSelf()
public java.lang.String toString()
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.
toString
in class java.lang.Object
protected java.lang.String decodeQueryPercents(java.lang.String url)
public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
toString()
public int hashCode()
null
(yes, we do break that contract),
this will return -1
.
hashCode
in class java.lang.Object
public java.lang.String encode(java.lang.Object obj)
URLEncoder.encode(java.lang.String)
using the configured character encoding.
public java.lang.String decode(java.lang.Object obj)
URLDecoder.decode(java.lang.String)
using the configured character encoding.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |