Project Set Up

To use the library in your project, simply add the following to your projects pom:

<dependency>
  <groupId>com.damnhandy</groupId>
  <artifactId>handy-uri-templates</artifactId>
  <version>${version}</version>
</dependency>

The latest version is:

You can also download the artifact directly at http://search.maven.org

Using the API

Using the library is simple:

String uri =  UriTemplate.fromTemplate("/{foo:1}{/foo,thing*}{?query,test2}")
                         .set("foo", "houses")
                         .set("query", "Ask something")
                         .set("test2", "something else")
                         .set("thing", "A test")
                         .expand();

This will result in the following URI:

"/h/houses/A%20test?query=Ask%20something&test2=someting%20else"

You can see more examples in some of the unit tests or you can read more in the JavaDocs.

Using with HTTP Clients

The API can be used with existing HTTP frameworks like the most excellent Async Http Client. Using the GitHub API, we can use the a UriTemplate to create a URI to look at this repository:

RequestBuilder builder = new RequestBuilder("GET");
Request request = builder.setUrl(
    UriTemplate.fromTemplate("https://api.github.com/repos{/user,repo,function,id}")
               .set("user", "damnhandy")
               .set("repo", "Handy-URI-Templates")
               .set("function","commits")
               .expand()).build();

When Request.getUrl() is called, it will return:

"https://api.github.com/repos/damnhandy/Handy-URI-Templates/commits"

Please have a look at the example test case for more details.

Usage with the Apache HTTP Client is just as similar.

Supported Value Types

While the set() method of the UriTemplate accepts any Java object, the following Java types are preferred:

• primitive and Object types such as:
• int & Integer
• double & Double
• char & Character
• float & Float
• double & Double
• short & Short
• long & Long
• Arrays of the above types
• java.util.List<Object>
• java.util.Map<String, Object%gt;
• java.util.Date. Dates will be formatted using the templates default formatter.
• Anything with a toString() method

Values that are not strings are rendered into the URI by calling its toString() method. Java objects can be treated as composite objects (as name/value pairs) when the variable specifies the explode modifier (see Composite Value below). A char[] or Character[] array will be treated as String. A multi dimensional character array will be treated as a List of Strings.

Unsupported Value Types

The template processor will not accept the following types of value combinations:

• with the exception of character arrays, multi dimensional arrays are not supported.
• Collections of Collections
• Maps that have values of type array, Collection, or Map.

If you need such data structures in a URI, consider implementing your own VarExploder to handle it.

Composite Values

The URI Template spec supports composite values where the variable may be a list of values of an associative array of (name, value) pairs. The template processor always treats lists as java.util.List and name/value pairs as a java.util.Map. Lists and Maps work with any supported type that is not anoth List, Map, or array.

POJOs as Composite Values

The template process can treat simple Java objects as composite value. When a POJO is set on a template variable and the variable specifies the an explode modifier “*”, a VarExploder is invoked. The purpose of the VarExploder is to expose the object properties as name/value pairs.

For most use cases, the DefaultVarExploder should be sufficient. The DefaultVarExploder is a VarExploder implementation that takes in a Java object and extracts the properties for use in a URI Template. This class is called by default when a POJO is passed into the UriTemplate and the explode modifier is present on the variable. Given the following URI template expression:

/mapper{?address*}

And this Java object for an address:

Address address = new Address();
address.setState("CA");
address.setCity("Newport Beach");
String result = UriTemplate.fromTemplate("/mapper{?address*}")
                           .set("address", address)
                           .expand();

The expanded URI will be:

/mapper?city=Newport%20Beach&state=CA

The DefaultVarExploder breaks down the object properties as follows:

• All properties that contain a non-null return value will be included
• Getters or fields annotated with @UriTransient will be excluded
• By default, the property name is used as the label in the URI. This can be overridden by placing the @VarName annotation on the field or getter method and specifying a name.
• Field level annotation take priority of getter annotations
• Property names are sorted in the order that they are found in the target class.

Please refer to the JavaDoc for more details on how the DefaultVarExploder works.

Should the DefaultVarExploder not be suitable for your needs, custom VarExploder implementations can be added by rolling your own implementation. A custom VarExploder implementation can be used by wrapping your object in your implementation:

UriTemplate.fromTemplate("/mapper{?address*}")
           .set("address", new MyCustomVarExploder(address))
           .expand();

Note: All VarExploder implementations are ONLY invoked when the explode modifier “*” is declared in the URI Template expression. If the variable declaration does not specify the explode modifier, an exception is raised.