com.aquenos.cassandra.pvarchiver.server.web.common.spring

Class UriExpander

java.lang.Object

com.aquenos.cassandra.pvarchiver.server.web.common.spring.UriExpander

public class UriExpander
extends Object

Expands URI templates that may contain URI variables and encodes them for being used in a view.

If the URI template starts with a forward slash ("/"), it is prepended with the context path of the web application. If it starts with a forward slash followed by a tilde ("~/"), the tilde is removed and the rest of the URI template is kept as is. In all other cases, the URI template is kept as is.

After transforming the URI template as described earlier, the URI template and the URI variables are passed to an internal instance of DefaultUriTemplateHandler. This instance has its "parse path" property set to true, so that URI variables used as path components can safely contain characters, in particular forward slashes, that would otherwise cause problems.

Finally, the resulting URI is converted to a String using URI.toASCIIString() and encoded using HttpServletResponse.encodeURL(String).

This class is mainly intended for use by the UriExpanderDialect.

Author:

Sebastian Marsching

Constructor Summary

Constructors

Constructor and Description
UriExpander(HttpServletRequest request, HttpServletResponse response) Creates a URI expander for the specified request and response.

Method Summary

Modifier and Type	Method and Description
String	encode(String string) Encodes a string so that it can safely be passed as a URI variable to one of the expand methods.
String	expand(String uriTemplate, Map<String,?> uriVariables) Expand the give URI template with a map of URI variables.
String	expand(String uriTemplate, Object... uriVariableValues) Expand the give URI template with an array of URI variable values.

Methods inherited from class java.lang.Object

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

Constructor Detail

UriExpander

public UriExpander(HttpServletRequest request,
                   HttpServletResponse response)

Creates a URI expander for the specified request and response. The HTTP servlet request is needed to determine the context path when the specified URI template is context-relative. The HTTP servlet response is needed to encode the resulting URI (so that session parameters get appended, if needed).

Parameters:

request - request to be used for determining the context path.

response - response to be used for encoding the resulting URI.

Method Detail

encode

public String encode(String string)

Encodes a string so that it can safely be passed as a URI variable to one of the expand methods.

In general, this method does not have to be used in order to produce a correct URI. The expand methods will always encode the URI in a way that it is correct according to the specification. However, such an URI may produce undesired results when being passed to a servlet container, because the container may decode it and interpret parts of it.

This method will call CustomUrlCodec.encode(String) and thus encode the string in a way that makes it opaque to any processing performed by a web server, servlet container, or other component that might intercept URIs. In particular, an encoded string can safely be used as a path segment or a matrix variable without effecting the path hierarchy, as characters like "/", "=", ".", and ";" are encoded in such a way that they do not get decoded when applying regular URL decoding.

On the other hand, an application receiving a string that has been encoded through this method has to decode it explicitly calling the CustomUrlCodec.decode(String) method.

Parameters:

string - string to be encoded.

Returns:

encoded string that is safe use anywhere in a URI path or query string.

expand

public String expand(String uriTemplate,
                     Map<String,?> uriVariables)

Expand the give URI template with a map of URI variables.

If the URI template starts with a forward slash ("/"), it is prepended with the context path of the web application. If it starts with a forward slash followed by a tilde ("~/"), the tilde is removed and the rest of the URI template is kept as is. In all other cases, the URI template is kept as is.

After transforming the URI template as described earlier, the URI template and the URI variables are passed to an internal instance of DefaultUriTemplateHandler. This instance has its "parse path" property set to true, so that URI variables used as path components can safely contain characters, in particular forward slashes, that would otherwise cause problems.

Finally, the resulting URI is converted to a String using URI.toASCIIString() and encoded using HttpServletResponse.encodeURL(String).

Parameters:

uriTemplate - the URI template string.

uriVariables - the URI variables.

Returns:

the resulting URI.

Throws:

IllegalArgumentException - if the uriTemplate cannot be handled by the underlying UriComponentsBuilder.

NullPointerException - if uriTemplate is null.

expand

public String expand(String uriTemplate,
                     Object... uriVariableValues)

Expand the give URI template with an array of URI variable values.

If the URI template starts with a forward slash ("/"), it is prepended with the context path of the web application. If it starts with a forward slash followed by a tilde ("~/"), the tilde is removed and the rest of the URI template is kept as is. In all other cases, the URI template is kept as is.

After transforming the URI template as described earlier, the URI template and the URI variables are passed to an internal instance of DefaultUriTemplateHandler. This instance has its "parse path" property set to true, so that URI variables used as path components can safely contain characters, in particular forward slashes, that would otherwise cause problems.

Finally, the resulting URI is converted to a String using URI.toASCIIString() and encoded using HttpServletResponse.encodeURL(String).

Parameters:

uriTemplate - the URI template string.

uriVariableValues - the URI variable values.

Returns:

the resulting URI

Throws:

IllegalArgumentException - if the uriTemplate cannot be handled by the underlying UriComponentsBuilder.

NullPointerException - if uriTemplate is null.