HATEOAS - RESTful Java with JAX-RS 2.0 - page 151

public public abstract abstract URI buildFromMap ( Map < String , ? extends extends Object > values )

throws throws IllegalArgumentException , UriBuilderException ;

public public abstract abstract URI buildFromEncodedMap (

Map < String , ? extends

extends Object > values )

throws throws IllegalArgumentException , UriBuilderException ;

public public abstract abstract URI build ( Object ... values )

throws

throws IllegalArgumentException , UriBuilderException ;

public public abstract abstract URI buildFromEncoded ( Object ... values )

throws

throws IllegalArgumentException , UriBuilderException ;

}

The build() methods create the actual URI. Before building the URI, though, any template
parameters you have defined must be filled in. The build() methods take either a map of
name/value pairs that can match up to named template parameters or you can provide a list
of values that will replace template parameters as they appear in the templated URI. These
values can either be encoded or decoded values, your choice. Let's look at a few examples:

UriBuilder builder = UriBuilder . fromPath ( "/customers/{id}" );
builder . scheme ( "http" )
. host ( "{hostname}" )
. queryParam ( "param={param}" );

In this code block, we have defined a URI pattern that looks like this:

http: //{hostname}/customers/{id}?param={param}

Since we have template parameters, we need to initialize them with values passed to one of
the build arguments to create the final URI. If you want to reuse this builder, you should
clone() it before calling a build() method, as the template parameters will be replaced in
the internal structure of the object:

UriBuilder clone = builder . clone ();
URI uri = clone . build ( "example.com" , "333" , "value" );

This code would create a URI that looks like this:

http: //example.com/customers/333?param=value

We can also define a map that contains the template values:

Map < String , Object > map = new new HashMap < String , Object >();

map . put ( "hostname" , "example.com" );
map . put ( "id" , 333 );
map . put ( "param" , "value" );

UriBuilder clone = builder . clone ();
URI uri = clone . buildFromMap ( map );