org.apache.ode.utils
Class URITemplate

java.lang.Object
  extended by 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:

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

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

Field Summary
static java.lang.String EXPANSION_REGEX
           
 
Constructor Summary
URITemplate()
           
 
Method Summary
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 void main(java.lang.String[] args)
           
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:

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:

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

main

public static void main(java.lang.String[] args)