UriTemplate (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web.util

## Class UriTemplate

- java.lang.Object
- - org.springframework.web.util.UriTemplate

- All Implemented Interfaces:
    Serializable

      public class UriTemplate
      extends Object
      implements Serializable

  Represents a URI template. A URI template is a URI-like String that contains variables enclosed by braces (`{}, {@code }`), which can be expanded to produce an actual URI.

  See `expand(Map)`, `expand(Object[])`, and `match(String)` for example usages.

  Since:
    3.0
  Author:
    Arjen Poutsma, Juergen Hoeller
  See Also:
    URI Templates, Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `UriTemplate(String uriTemplate)` Construct a new `UriTemplate` with the given URI String.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected URI` | `encodeUri(String uri)` Deprecated. No longer in use, with no direct replacement
    `URI` | `expand(Map<String,?> uriVariables)` Given the Map of variables, expands this template into a URI.
    `URI` | `expand(Object... uriVariableValues)` Given an array of variables, expand this template into a full URI.
    `List<String>` | `getVariableNames()` Return the names of the variables in the template, in order.
    `Map<String,String>` | `match(String uri)` Match the given URI to a map of variable values.
    `boolean` | `matches(String uri)` Indicate whether the given URI matches this template.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### UriTemplate

          public UriTemplate(String uriTemplate)

      Construct a new `UriTemplate` with the given URI String.
      Parameters:
        `uriTemplate` - the URI template string

  - ### Method Detail

    - #### getVariableNames

          public List<String> getVariableNames()

      Return the names of the variables in the template, in order.
      Returns:
        the template variable names

    - #### expand

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

      Given the Map of variables, expands this template into a URI. The Map keys represent variable names, the Map values variable values. The order of variables is not significant.

      Example:

           UriTemplate template = new UriTemplate("http://example.com/hotels/{hotel}/bookings/{booking}");
           Map<String, String> uriVariables = new HashMap<String, String>();
           uriVariables.put("booking", "42");
           uriVariables.put("hotel", "1");
           System.out.println(template.expand(uriVariables));

      will print:

      > `http://example.com/hotels/1/bookings/42`

      Parameters:
        `uriVariables` - the map of URI variables
      Returns:
        the expanded URI
      Throws:
        `IllegalArgumentException` - if `uriVariables` is `null`; or if it does not contain values for all the variable names

    - #### expand

          public URI expand(Object... uriVariableValues)

      Given an array of variables, expand this template into a full URI. The array represent variable values. The order of variables is significant.

      Example:

           UriTemplate template = new UriTemplate("http://example.com/hotels/{hotel}/bookings/{booking}");
           System.out.println(template.expand("1", "42));

      will print:

      > `http://example.com/hotels/1/bookings/42`

      Parameters:
        `uriVariableValues` - the array of URI variables
      Returns:
        the expanded URI
      Throws:
        `IllegalArgumentException` - if `uriVariables` is `null` or if it does not contain sufficient variables

    - #### matches

          public boolean matches(String uri)

      Indicate whether the given URI matches this template.
      Parameters:
        `uri` - the URI to match to
      Returns:
        `true` if it matches; `false` otherwise

    - #### match

          public Map<String,String> match(String uri)

      Match the given URI to a map of variable values. Keys in the returned map are variable names, values are variable values, as occurred in the given URI.

      Example:

           UriTemplate template = new UriTemplate("http://example.com/hotels/{hotel}/bookings/{booking}");
           System.out.println(template.match("http://example.com/hotels/1/bookings/42"));

      will print:

      > `{hotel=1, booking=42}`

      Parameters:
        `uri` - the URI to match to
      Returns:
        a map of variable values

    - #### encodeUri

          @Deprecated
          protected URI encodeUri(String uri)

      Deprecated. No longer in use, with no direct replacement
      Encodes the given String as URL.

      Defaults to `UriUtils.encodeUri(String, String)`.

      Parameters:
        `uri` - the URI to encode
      Returns:
        the encoded URI

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`