Class UriTemplate

java.lang.Object
org.springframework.web.util.UriTemplate
All Implemented Interfaces:
Serializable

public class UriTemplate extends Object implements Serializable
Representation of a URI template that can be expanded with URI variables via expand(Map) or expand(Object[]), or matched to a URL via match(String). This class is designed to be thread-safe and reusable, and allows any number of expand or match calls.

Note: this class uses UriComponentsBuilder internally to expand URI templates, and is merely a shortcut for already prepared URI templates. For more dynamic preparation and extra flexibility, for example, around URI encoding, consider using UriComponentsBuilder or the higher level DefaultUriBuilderFactory which adds several encoding modes on top of UriComponentsBuilder. See the reference docs for further details.

Since:
3.0
Author:
Arjen Poutsma, Juergen Hoeller, Rossen Stoyanchev
See Also:
  • Constructor Details

    • UriTemplate

      public UriTemplate(String uriTemplate)
      Construct a new UriTemplate with the given URI String.
      Parameters:
      uriTemplate - the URI template string
  • Method Details

    • getVariableNames

      public List<String> getVariableNames()
      Return the names of the variables in this template, in order.
      Returns:
      the template variable names
    • expand

      public URI expand(Map<String,?> uriVariables)
      Given the Map of variables, expand this template into a URI.

      The Map keys represent variable names, and the Map values represent variable values. The order of variables is not significant.

      Example:

       UriTemplate template = new UriTemplate("https://example.com/hotels/{hotel}/bookings/{booking}");
       Map<String, String> uriVariables = Map.of(
           "booking", "42",
           "hotel", "Rest & Relax");
       System.out.println(template.expand(uriVariables));
      will print:
      https://example.com/hotels/Rest%20%26%20Relax/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 the array of variables, expand this template into a full URI.

      The array represents variable values, and the order of variables is significant.

      Example:

       UriTemplate template = new UriTemplate("https://example.com/hotels/{hotel}/bookings/{booking}");
       System.out.println(template.expand("Rest & Relax", 42));
      will print:
      https://example.com/hotels/Rest%20%26%20Relax/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(@Nullable 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 based on this template.

      Keys in the returned map are variable names, and the values in the returned map are variable values, as present in the given URI.

      Example:

       UriTemplate template = new UriTemplate("https://example.com/hotels/{hotel}/bookings/{booking}");
       System.out.println(template.match("https://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
    • toString

      public String toString()
      Overrides:
      toString in class Object