JarCastingHandy URI Templates
Handy URI Templates is a uritemplate processor implementing RFC6570 written in Java. If you are looking for a non-Java implementation, please check the RFC6570 implementations page. The current implementation is based on the final release of the uri template spec. The template processor supports the following features:
- Fluent Java API for manipulating uritemplates
- Supports up to level 4 template expressions including prefix and explode modifiers
- Strong validation and error reporting
- Java objects as template values
- Support for rendering date values
- Template expression validation
- Custom object expanders
- Support for Jackson serializers and deserializers.
- Support for partial template expansion
As of version 1.1.1, Handy URI Templates passes all tests defined by the uritemplate-test suite.
You can view code coverage here.
The complete JavaDocs are here.
API Documentation
JavaDocs are available on Javadocs.io
Maven
To use the latest version of Handy URI Templates, you need to add the following dependency to your pom.xml:
<dependency>
<groupId>com.damnhandy</groupId>
<artifactId>handy-uri-templates</artifactId>
<version>2.1.7</version>
</dependency>
The next version of Handy URI Templates includes some big changes to the API. If you want to be daring, you can use the SNAPSHOT release:
<dependency>
<groupId>com.damnhandy</groupId>
<artifactId>handy-uri-templates</artifactId>
<version>2.1.8-SNAPSHOT</version>
</dependency>
In order to use a SNAPSHOT release, you'll have to add the Sonatype snapshots repository:
<repository>
<id>sonatype-nexus-snapshots</id>
<name>sonatype-nexus-snapshots</name>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
</repository>
You can also download the artifact directly at http://search.maven.org
Basic Usage
Using the library is simple:
String uri = UriTemplate.fromTemplate("/{foo:1}{/foo,thing*}{?query,test2}")
.set("foo", "houses")
.set("query", "Ask something")
.set("test2", "someting 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 find more in the JavaDocs.
URI Template Builder API
Starting in version 2.x, the UriTemplateBuilder was added to make it easier to programatically construct URI templates. It's used like this:
UriTemplate template =
UriTemplate.buildFromTemplate("http://example.com")
.literal("/foo")
.path(var("thing1"),var("explodedThing", true))
.fragment(var("prefix", 2))
.build();
This will yield the following URL template string:
"http://example.com/foo{/thing1,explodedThing*}{#prefix:2}"
This API is still a work in progress an feedback is appreciated.
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
- UUID
- Enums
- Arrays of the above types
java.util.List<Object>java.util.Map<String, Object>java.util.DateDates will be formatted using the template's 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 another List, Map, or array.
POJOs as Composite Values
The template processor 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
@UriTransientwill be excluded - By default, the property name is used as the label in the URI. This can be overridden by placing the
@VarNameannotation on the field or getter method and specifying a name. - Field level annotations take priority over 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.
License
Copyright 2011-2016 Ryan J. McDonough
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.