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

    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`