org.apache.ode.utils

Class URITemplate

java.lang.Object

org.apache.ode.utils.URITemplate

public class URITemplate
extends java.lang.Object

A partial implementation of URI Template expansion as specified by the URI template specification.

Limitations
The only operation implemented so far is Var substitution. If an expansion template for another operation (join, neg, opt, etc) is found, an UnsupportedOperationException is thrown.

Escaping Considerations
Replacement and default values are escaped. All characters except unreserved (as defined by rfc2396) are escaped.
unreserved = alphanum | mark
mark = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"

Rfc2396 is used to be compliant with java.net.URI.

Examples:
Given the following template variable names and values:

• foo = tag
• bar = java
• name = null
• date = 2008/05/09

The following URI Templates will be expanded as shown:
http://example.com/{foo}/{bar}.{format=xml}
http://example.com/tag/java.xml

http://example.com/tag/java.{format}
http://example.com/tag/java.

http://example.com/{foo}/{name}
http://example.com/tag/

http://example.com/{foo}/{name=james}
http://example.com/tag/james

http://example.org/{date}
http://example.org/2008%2F05%2F09

http://example.org/{-join|&|foo,bar,xyzzy,baz}/{date}
--> UnsupportedOperationException

Author:

Alexis Midon

See Also:

varSubstitution(String, Object[], java.util.Map)

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	EXPANSION_REGEX

Constructor Summary

Constructors

Constructor and Description
URITemplate()

Method Summary

Methods

Modifier and Type	Method and Description
static java.lang.String	expand(java.lang.String uriTemplate, java.util.Map<java.lang.String,java.lang.String> nameValuePairs) A partial implementation of URI Template expansion as specified by the URI template specification.
static java.lang.String	expand(java.lang.String uriTemplate, java.lang.String... nameValuePairs) Simply build a map from nameValuePairs and pass it to expand(String, java.util.Map)
static java.lang.String	expandLazily(java.lang.String uriTemplate, java.util.Map<java.lang.String,java.lang.String> nameValuePairs) Same as expand(String, java.util.Map) but preserve an expansion template if the corresponding variable is not defined in the nameValuePairs map (i.e.
static java.lang.String	expandLazily(java.lang.String uriTemplate, java.lang.String... nameValuePairs)
static java.lang.Object[]	parseExpansion(java.lang.String expansion) Implements the function describes in the spec
static java.lang.String	varSubstitution(java.lang.String expansionPattern, java.lang.Object[] expansionInfo, java.util.Map<java.lang.String,java.lang.String> nameValuePairs) An implementation of var substitution as defined by the URI template specification.
static java.lang.String	varSubstitution(java.lang.String expansionPattern, java.lang.Object[] expansionInfo, java.util.Map<java.lang.String,java.lang.String> nameValuePairs, boolean preserveUndefinedVar) Same as varSubstitution(String, Object[], java.util.Map) but the preserveUndefinedVar boolean argument (if true) allows to preserve an expansion template if the corresponding variable is not defined in the nameValuePairs map (i.e.

Methods inherited from class java.lang.Object

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

Field Detail

EXPANSION_REGEX

public static final java.lang.String EXPANSION_REGEX

See Also:

Constant Field Values

Constructor Detail

URITemplate

public URITemplate()

Method Detail

parseExpansion

public static java.lang.Object[] parseExpansion(java.lang.String expansion)

Implements the function describes in the spec

Parameters:

expansion, - an expansion template (with the surrounding braces)

Returns:

an array of object containing the operation name, the operation argument, a map of

expand

public static java.lang.String expand(java.lang.String uriTemplate,
                      java.lang.String... nameValuePairs)
                               throws org.apache.commons.httpclient.URIException,
                                      java.lang.UnsupportedOperationException

Simply build a map from nameValuePairs and pass it to expand(String, java.util.Map)

Parameters:

nameValuePairs - an array containing of name, value, name, value, and so on. Null values are allowed.

Throws:

org.apache.commons.httpclient.URIException

java.lang.UnsupportedOperationException

See Also:

expand (String, java.util.Map)

expand

public static java.lang.String expand(java.lang.String uriTemplate,
                      java.util.Map<java.lang.String,java.lang.String> nameValuePairs)
                               throws org.apache.commons.httpclient.URIException,
                                      java.lang.UnsupportedOperationException

A partial implementation of URI Template expansion as specified by the URI template specification.

The only operation implemented as of today is "Var Substitution". If an expansion template for another operation (join, neg, opt, etc) is found, an UnsupportedOperationException will be thrown.

See varSubstitution(String, Object[], java.util.Map)

Parameters:

uriTemplate - the URI template

nameValuePairs - a Map of <name, value>. Null values are allowed.

Returns:

a copy of uri template in which substitutions have been made (if possible)

Throws:

org.apache.commons.httpclient.URIException - if the default protocol charset is not supported

java.lang.UnsupportedOperationException - if the operation is not supported. Currently only var substitution is supported.

See Also:

varSubstitution(String, Object[], java.util.Map)

expandLazily

public static java.lang.String expandLazily(java.lang.String uriTemplate,
                            java.util.Map<java.lang.String,java.lang.String> nameValuePairs)
                                     throws org.apache.commons.httpclient.URIException,
                                            java.lang.UnsupportedOperationException

Same as expand(String, java.util.Map) but preserve an expansion template if the corresponding variable is not defined in the nameValuePairs map (i.e. map.contains(var)==false).
Meaning that a template may be returned.
If a default value exists for the undefined value, it will be used to replace the expansion pattern.

Beware that this behavior deviates from the URI Template specification.

For instance:
Given the following template variable names and values:

• bar = java
• foo undefined

The following expansion templates will be expanded as shown if preserveUndefinedVar is true:
http://example.com/{bar}
http://example.com/java

{foo=a_default_value}
a_default_value

http://example.com/{bar}/{foo}
http://example.com/java/{foo}

Throws:

org.apache.commons.httpclient.URIException

java.lang.UnsupportedOperationException

See Also:

expand(String, java.util.Map)

expandLazily

public static java.lang.String expandLazily(java.lang.String uriTemplate,
                            java.lang.String... nameValuePairs)
                                     throws org.apache.commons.httpclient.URIException

Throws:

org.apache.commons.httpclient.URIException

See Also:

expandLazily(String, java.util.Map)

varSubstitution

public static java.lang.String varSubstitution(java.lang.String expansionPattern,
                               java.lang.Object[] expansionInfo,
                               java.util.Map<java.lang.String,java.lang.String> nameValuePairs)
                                        throws org.apache.commons.httpclient.URIException

An implementation of var substitution as defined by the URI template specification.

If for a given variable, the variable is in the name/value map but the associated value is null. The variable will be replaced with an empty string or with the default value if any.

Parameters:

expansionPattern - an expansion pattern (not a uri template) e.g. "{foo}"

expansionInfo - the result of parseExpansion(String) for the given expansion pattern

nameValuePairs - the Map of names and associated values. May containt null values.

Returns:

the expanded string, properly escaped.

Throws:

org.apache.commons.httpclient.URIException - if an encoding exception occured

See Also:

URIUtil.encodeWithinQuery(String), URI

varSubstitution

public static java.lang.String varSubstitution(java.lang.String expansionPattern,
                               java.lang.Object[] expansionInfo,
                               java.util.Map<java.lang.String,java.lang.String> nameValuePairs,
                               boolean preserveUndefinedVar)
                                        throws org.apache.commons.httpclient.URIException

Same as varSubstitution(String, Object[], java.util.Map) but the preserveUndefinedVar boolean argument (if true) allows to preserve an expansion template if the corresponding variable is not defined in the nameValuePairs map (i.e. map.contains(var)==false).
If a default value exists for the undefined value, it will be used to replace the expansion pattern.

Beware that this behavior deviates from the URI Template specification.

For instance:
Given the following template variable names and values:

• bar = java
• foo undefined

The following expansion templates will be expanded as shown if preserveUndefinedVar is true:
{bar}
java

{foo=a_default_value}
a_default_value

{foo}
{foo}

Throws:

org.apache.commons.httpclient.URIException