Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

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 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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD