(Quick Reference)

5 UriBuilder - Reference Documentation

Authors: Bud Byrd

Version: 2.0.2

Table of Contents

5 UriBuilder

The plugin also provides a UriBuilder class to make building URLs with correct escaping simpler. This builder follows the same building conventions as the Jersey Request Builder.

5.1 Properties

PropertyDescriptionType
baseBase URL to start from.String
hostHost name part of the URL.String
portRemote host port number.Integer
pathA list of path parts to add to the URL.List
queryA key/value pair map of query parameters to add to the URL.Map
schemeThe protocol scheme to use (http, https, etc).String
fragmentFragment part of the URL (index.html#fragment).String

Note that if the base property is used, any of its URI parts will be overridden by any of the individual properties, if set. The exception is the path property, which will append the path parts to the path of the base URL that was specified.
The UriBuilder returns a URI object, which can be assigned to the uri property of the Jersey Request Builder.

5.2 Examples

Building a URI with the DSL-based syntax:
// Produces "http://grails.org/doc/2.1.1/guide/introduction.html#coreFeatures"
UriBuilder.build {
    base = 'http://grails.org'
    path = ['doc', '2.1.1', 'guide', 'introduction.html']
    fragment = 'coreFeatures'
}

Similarly, the URI can be built gradually:

// Produces "http://grails.org/doc/2.1.1/guide/introduction.html#coreFeatures"
UriBuilder uriBuilder = new UriBuilder()
uriBuilder.base = 'http://grails.org'
uriBuilder.path = ['doc', '2.1.1', 'guide', 'introduction.html']
uriBuilder.fragment = 'coreFeatures'
uriBuilder.build()

UriBuilder is typically used with static build methods, but if the gradual method is used (as in the example above), UriBuilder will need to be instantiated.

The URI builder supports path substitution as a convenience feature. You can not build a URI this way, but this allows authors to use a predefined URL "pattern" to replace path pieces with values determined at runtime. For example:

// Produces "http://example.com/webapp/resource/item/id/5497"
UriBuilder.build("http://example.com/webapp/resource/{resource}/id/{id}", "item", "5497")