mattbishop/uri-template

Read me first

The license of this project is LGPLv3 or later. See file src/main/resources/LICENSE for the full text.

What this is

This is a 100% Java implementation of IETF's RFC 6570 (URI templates). This RFC is used, among others, in JSON Schema hyperschema.

Versions

The project is still under development. The current version is 0.3.

Status

Existing tests for this implementation are based on two sources:

the RFC itself;
the uritemplate-test testuite.

All tests from the RFC itself pass. However, with regards to the second source, tests involving empty lists and/or empty associative arrays do not pass -- that is, not all of them.

The reason is that some of these tests cover a gray area of the RFC; in some situations, empty lists/associative array expansions are not clearly defined. Currently, the implementation acts in such a way that it does not agree with the aforementioned source.

As a consequence, further clarification is needed (in the shape of an errata) with regards to empty lists/associative arrays. When such an errata is available, this implementation will comply to it.

See below for a sample code usage.

Maven artifact

<dependency>
    <groupId>com.github.fge</groupId>
    <artifactId>uri-template</artifactId>
    <version>your-version-here</version>
</dependency>

Sample code usage

First you need to build your map of values. As this is totally application dependent, this application only offers facilities to create values according to their type (which this implementation calls "scalar", "list" and "map"). Example:

final Map<String, VariableValue> vars = new HashMap<String, VariableValue>();

String name;
VariableValue value;

// Create a scalar value
name = "scalar";
value = new ScalarValue("hello");
vars.put(name, value);

// Create a list value
name = "list";
value = new ListValue(Arrays.asList("one", "two", "three"));
vars.put(name, value);

// Create a map value -- note: uses Guava's ImmutableMap
name = "map";
value = new MapValue(ImmutableMap.of("key1", "value1", "key2", "value2"));
vars.put(name, value);

Then, you need to create a URI template. This is done using the `URITemplate` class:

final URITemplate template = new URITemplate("http://foo.bar/myPage{?map*}");

// Will print out "http://foo.bar/myPage?key1=value1&key2=value2"
System.out.println(template.expand(vars));

See the RFC for more sample usages.

mattbishop / uri-template