Package 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	Description
UriTemplate	build()	Generates a UriTemplate instance from the builder.
UriTemplateBuilder	continuation(VarSpec... var)	Appends a template expression using the form-style query continuation and and optional modifier.
UriTemplateBuilder	continuation(String... var)	Appends a template expression using the form-style query continuation.
UriTemplateBuilder	fragment(VarSpec... var)	Appends a template expression using the fragment operator (#) with a modifier.
UriTemplateBuilder	fragment(String... var)	Appends a template expression using the fragment operator (#).
UriTemplateComponent[]	getComponents()	Returns an array of the components in the Builder.
UriTemplateBuilder	label(VarSpec... var)	Appends a template expression using the label (.) operator and modifier.
UriTemplateBuilder	label(String... var)	Appends a template expression using the label (.) operator.
UriTemplateBuilder	literal(String string)	Appends a Literal value to the UriTemplate.
UriTemplateBuilder	matrix(VarSpec... var)	Appends a template expression using the matrix (;) operator and modifier.
UriTemplateBuilder	matrix(String... var)	Appends a template expression using the matrix (;) operator.
UriTemplateBuilder	path(VarSpec... var)	Appends a template expression using the path (/) operator and modifier.
UriTemplateBuilder	path(String... var)	Appends a template expression using the path (/) operator.
UriTemplateBuilder	query(VarSpec... var)	Appends a template expression using the query (?) operator and and optional modifier.
UriTemplateBuilder	query(String... var)	Appends a template expression using the query (?) operator.
UriTemplateBuilder	reserved(VarSpec... var)	Appends a template expression using the reserved operator (+) along with an optional modifier.
UriTemplateBuilder	reserved(String... var)	Appends a template expression using the reserved operator (+).
UriTemplateBuilder	simple(VarSpec... var)	Appends a template expression using no operator but with an optional modifier.
UriTemplateBuilder	simple(String... var)	Appends a template expression using no operator.
UriTemplateBuilder	template(UriTemplate... template)	Parses the template and appends the parsed components to the builder.
UriTemplateBuilder	template(String... 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(String dateFormatString)
UriTemplateBuilder	withDefaultDateFormat(DateFormat dateFormat)	Deprecated. replaced by withDefaultDateFormat

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 - the date format to use internally

Returns:

the UriTemplateBuilder

Since:

2.0

withDefaultDateFormat

@Deprecated
public UriTemplateBuilder withDefaultDateFormat(DateFormat dateFormat)

Deprecated.

replaced by withDefaultDateFormat

Parameters:

dateFormat - the date format to use internally

Returns:

the UriTemplateBuilder

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 - the literal 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 - the name of the variable

Returns:

the UriTemplateBuilder

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 - the varspec

Returns:

the UriTemplateBuilder

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 - the varspec name

Returns:

the UriTemplateBuilder

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 - the varspec

Returns:

the UriTemplateBuilder

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 - the varspec name

Returns:

the UriTemplateBuilder

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 - the varspec

Returns:

the UriTemplateBuilder

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 - the varspec name

Returns:

the UriTemplateBuilder

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 - the varspec

Returns:

the UriTemplateBuilder

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 - the varspec name

Returns:

the UriTemplateBuilder

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 - the varspec

Returns:

the UriTemplateBuilder

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 - the varspec name

Returns:

the UriTemplateBuilder

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 - the varspec

Returns:

the UriTemplateBuilder

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 - the varspec name

Returns:

the UriTemplateBuilder

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 - the varspec

Returns:

the UriTemplateBuilder

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 - the varspec name

Returns:

the UriTemplateBuilder

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 - the varspec

Returns:

the UriTemplateBuilder

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 - the uri template

Returns:

the UriTemplateBuilder

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 - the uri template string

Returns:

the uri template builder

getComponents

public UriTemplateComponent[] getComponents()

Returns an array of the components in the Builder.

Returns:

array of the components in the Builder

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 - the varspec name

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 - the varspec name

explode - boolean to indicate that this VarSpec should use the explode modifer

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 - the varspec name

prefix - the prefix position

Returns:

the VarSpec for the specified name