Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
com.damnhandy:handy-uri-templates
Advanced tools
Handy URI Templates is a RFC6570 compliant URI template processor. The library allows clients to utilize templatized URIs and inject replacement variables to expand the template into a URI. The library sports a fluent API, ability to plugin custom object renderers, and supports all levels of 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:
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.
JavaDocs are available on Javadocs.io
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
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.
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.
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.
While the set()
method of the UriTemplate accepts any Java object, the following Java types are preferred:
java.util.List<Object>
java.util.Map<String, Object>
java.util.Date
Dates will be formatted using the template's default formatter.toString()
methodValues 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.
The template processor will not accept the following types of value combinations:
If you need such data structures in a URI, consider implementing your own VarExploder
to handle it.
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.
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:
@UriTransient
will be excluded@VarName
annotation on the field or getter method and specifying a name.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.
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.
FAQs
Handy URI Templates is a RFC6570 compliant URI template processor. The library allows clients to utilize templatized URIs and inject replacement variables to expand the template into a URI. The library sports a fluent API, ability to plugin custom object renderers, and supports all levels of URI templates.
We found that com.damnhandy:handy-uri-templates demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.