com.damnhandy.uri.template

Class UriTemplateBuilder

java.lang.Object

com.damnhandy.uri.template.UriTemplateBuilder

public final class UriTemplateBuilder
extends Object

A utility class used for programatically generating a UriTemplate. The class can be used as follows:

 UriTemplate template = UriTemplate.buildFromTemplate("http://example.com")
                                   .literal("/foo")
                                   .path(var("thing1"), var("explodedThing", true))
                                   .fragment(var("prefix", 2))
                                   .build();
 

This code will return a UriTemplate with the following value:

 http://example.com/foo{/thing1,explodedThing*}{#prefix:2}
 

Version:

$Revision: 1.1 $

Author:

Ryan J. McDonough

Method Summary

Modifier and Type	Method and Description
UriTemplate	build() Generates a UriTemplate instance from the builder.
UriTemplateBuilder	continuation(String... var) Appends a template expression using the form-style query continuation.
UriTemplateBuilder	continuation(VarSpec... var) Appends a template expression using the form-style query continuation and and optional modifier.
UriTemplateBuilder	fragment(String... var) Appends a template expression using the fragment operator (#).
UriTemplateBuilder	fragment(VarSpec... var) Appends a template expression using the fragment operator (#) with a modifier.
UriTemplateComponent[]	getComponents() Returns an array of the components in the Builder.
UriTemplateBuilder	label(String... var) Appends a template expression using the label (.) operator.
UriTemplateBuilder	label(VarSpec... var) Appends a template expression using the label (.) operator and modifier.
UriTemplateBuilder	literal(String string) Appends a Literal value to the UriTemplate.
UriTemplateBuilder	matrix(String... var) Appends a template expression using the matrix (;) operator.
UriTemplateBuilder	matrix(VarSpec... var) Appends a template expression using the matrix (;) operator and modifier.
UriTemplateBuilder	path(String... var) Appends a template expression using the path (/) operator.
UriTemplateBuilder	path(VarSpec... var) Appends a template expression using the path (/) operator and modifier.
UriTemplateBuilder	query(String... var) Appends a template expression using the query (?) operator.
UriTemplateBuilder	query(VarSpec... var) Appends a template expression using the query (?) operator and and optional modifier.
UriTemplateBuilder	reserved(String... var) Appends a template expression using the reserved operator (+).
UriTemplateBuilder	reserved(VarSpec... var) Appends a template expression using the reserved operator (+) along with an optional modifier.
UriTemplateBuilder	simple(String... var) Appends a template expression using no operator.
UriTemplateBuilder	simple(VarSpec... var) Appends a template expression using no operator but with an optional modifier.
UriTemplateBuilder	template(String... template) Parses the template and appends the parsed components to the builder.
UriTemplateBuilder	template(UriTemplate... template) Parses the template and appends the parsed components to the builder.
static VarSpec	var(String varName) Adds a variable name to the expression.
static VarSpec	var(String varName, boolean explode) Adds a variable name to the expression with an explode modifier.
static VarSpec	var(String varName, int prefix) Adds a variable name to the expression with a prefix modifier.
UriTemplateBuilder	withDefaultDateFormat(DateFormat dateFormat) Deprecated. replaced by withDefaultDateFormat
UriTemplateBuilder	withDefaultDateFormat(String dateFormatString)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

withDefaultDateFormat

public UriTemplateBuilder withDefaultDateFormat(String dateFormatString)

Parameters:

dateFormatString -

Returns:

Since:

2.0

withDefaultDateFormat

@Deprecated
public UriTemplateBuilder withDefaultDateFormat(DateFormat dateFormat)

Deprecated. replaced by withDefaultDateFormat

Parameters:

dateFormat -

Returns:

Since:

2.0

literal

public UriTemplateBuilder literal(String string)

Appends a Literal value to the UriTemplate. The following code:

 UriTemplate template = UriTemplate.buildFromTemplate("http://example.com")
                                   .literal("/foo")
                                   .build();
 

Will generate the following template:

 http://example.com/foo
 

Note that this particular example has no expressions, so it's not a valid URI template.

Parameters:

string -

Returns:

simple

public UriTemplateBuilder simple(String... var)

Appends a template expression using no operator. The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .simple("foo")
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{foo}
 

Parameters:

var -

Returns:

simple

public UriTemplateBuilder simple(VarSpec... var)

Appends a template expression using no operator but with an optional modifier. The following code:

 import static com.damnhandy.uri.template.UriTemplateBuilder.var;

 ...

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .simple(var("foo",true))
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{foo*}
 

Parameters:

var -

Returns:

reserved

public UriTemplateBuilder reserved(String... var)

Appends a template expression using the reserved operator (+). The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .reserved("foo")
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{+foo}
 

Parameters:

var -

Returns:

reserved

public UriTemplateBuilder reserved(VarSpec... var)

Appends a template expression using the reserved operator (+) along with an optional modifier. The following code:

 import static com.damnhandy.uri.template.UriTemplateBuilder.var;

 ...

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .reserved(var("foo",1))
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{+foo:1}
 

Parameters:

var -

Returns:

fragment

public UriTemplateBuilder fragment(String... var)
                            throws UriTemplateBuilderException

Appends a template expression using the fragment operator (#). The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .fragement("foo")
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{#foo}
 

Parameters:

var -

Returns:

Throws:

UriTemplateBuilderException - if you attempt to add more than one fragment expression, a UriTemplateBuilderException will be raised

fragment

public UriTemplateBuilder fragment(VarSpec... var)
                            throws UriTemplateBuilderException

Appends a template expression using the fragment operator (#) with a modifier. The following code:

 import static com.damnhandy.uri.template.UriTemplateBuilder.var;

 ...

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .fragement(var("foo", 1))
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{#foo:1}
 

Parameters:

var -

Returns:

Throws:

UriTemplateBuilderException - if you attempt to add more than one fragment expression, a UriTemplateBuilderException will be raised

label

public UriTemplateBuilder label(String... var)

Appends a template expression using the label (.) operator. The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .label("foo")
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{.foo}
 

Parameters:

var -

Returns:

label

public UriTemplateBuilder label(VarSpec... var)

Appends a template expression using the label (.) operator and modifier. The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .label(var("foo", true))
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{.foo*}
 

Parameters:

var -

Returns:

matrix

public UriTemplateBuilder matrix(String... var)

Appends a template expression using the matrix (;) operator. The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .matrix("foo")
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{;foo}
 

Parameters:

var -

Returns:

matrix

public UriTemplateBuilder matrix(VarSpec... var)

Appends a template expression using the matrix (;) operator and modifier. The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .matrix(var("foo", true))
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{;foo*}
 

Parameters:

var -

Returns:

path

public UriTemplateBuilder path(String... var)

Appends a template expression using the path (/) operator. The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com")
                   .path("foo")
                   .build();
 

Will generate the following URI Template string:

 http://example.com{/foo}
 

Parameters:

var -

Returns:

path

public UriTemplateBuilder path(VarSpec... var)

Appends a template expression using the path (/) operator and modifier. The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com")
                   .path(var("foo", 1))
                   .build();
 

Will generate the following URI Template string:

 http://example.com{/foo:1}
 

Parameters:

var -

Returns:

query

public UriTemplateBuilder query(String... var)

Appends a template expression using the query (?) operator. The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .query("foo")
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{?foo}
 

Parameters:

var -

Returns:

query

public UriTemplateBuilder query(VarSpec... var)

Appends a template expression using the query (?) operator and and optional modifier. The following code:

 import static com.damnhandy.uri.template.UriTemplateBuilder.var;

 ...

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .query(var("foo",1))
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{?foo:1}
 

Parameters:

var -

Returns:

continuation

public UriTemplateBuilder continuation(String... var)

Appends a template expression using the form-style query continuation. The following code:

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .continuation("foo")
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{&foo}
 

Parameters:

var -

Returns:

continuation

public UriTemplateBuilder continuation(VarSpec... var)

Appends a template expression using the form-style query continuation and and optional modifier. The following code:

 import static com.damnhandy.uri.template.UriTemplateBuilder.var;

 ...

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .query(var("foo",1))
                   .build();
 

Will generate the following URI Template string:

 http://example.com/{&foo:1}
 

Parameters:

var -

Returns:

template

public UriTemplateBuilder template(UriTemplate... template)

Parses the template and appends the parsed components to the builder. The following code:

 import static com.damnhandy.uri.template.UriTemplateBuilder.var;

 ...

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .template("foo/{id}{?filter}")
                   .build();
 

Will generate the following URI Template string:

 http://example.com/foo/{id}{?filter}
 

Parameters:

template -

Returns:

template

public UriTemplateBuilder template(String... template)

Parses the template and appends the parsed components to the builder. The following code:

 import static com.damnhandy.uri.template.UriTemplateBuilder.var;

 ...

 UriTemplate template =
        UriTemplate.buildFromTemplate("http://example.com/")
                   .template("foo/{id}{?filter}")
                   .build();
 

Will generate the following URI Template string:

 http://example.com/foo/{id}{?filter}
 

Parameters:

template -

Returns:

getComponents

public UriTemplateComponent[] getComponents()

Returns an array of the components in the Builder.

Returns:

build

public UriTemplate build()
                  throws MalformedUriTemplateException

Generates a UriTemplate instance from the builder.

Returns:

the UriTemplate

Throws:

MalformedUriTemplateException

Since:

2.0

var

public static VarSpec var(String varName)

Adds a variable name to the expression.

 var("foo");
 

Will yield the following expression:

 {foo}
 

Parameters:

varName -

Returns:

the VarSpec for the specified name

var

public static VarSpec var(String varName,
                          boolean explode)

Adds a variable name to the expression with an explode modifier.

 var("foo",true);
 

Will yield the following expression:

 {foo*}
 

Parameters:

varName -

explode -

Returns:

the VarSpec for the specified name

var

public static VarSpec var(String varName,
                          int prefix)

Adds a variable name to the expression with a prefix modifier.

 var("foo",2);
 

Will yield the following expression:

 {foo:2}
 

Parameters:

varName -

prefix -

Returns:

the VarSpec for the specified name