com.damnhandy.uri.template

Class UriTemplate

java.lang.Object

com.damnhandy.uri.template.UriTemplate

All Implemented Interfaces:

Serializable

public class UriTemplate
extends Object
implements Serializable

This is the primary class for creating and manipulating URI templates. This project implements RFC6570 URI Templates and produces output that is compliant with the spec. The template processor supports levels 1 through 4. In addition to supporting Map and List values as composite types, the library also supports the use of Java objects as well. Please see the VarExploder and DefaultVarExploder for more info.

Basic Usage:

There are many ways to use this library. The simplest way is to create a template from a URI template string:

 UriTemplate template = UriTemplate.fromTemplate("http://example.com/search{?q,lang}");
 

Replacement values are added by calling the set(String, Object) method on the template:

 template.set("q","cat")
         .set("lang","en");
 String uri = template.expand();
 

The expand() method will replace the variable names with the supplied values and return the following URI:

 http://example.com/search?q=cat&lang=en
 

Since:

1.0

Version:

$Revision: 1.1 $

Author:

Ryan J. McDonough

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UriTemplate.Encoding

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_SEPARATOR
protected DateFormat	defaultDateFormat Deprecated. Replaced by defaultDateTimeFormatter

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	UriTemplate(LinkedList<UriTemplateComponent> components) Create a new UriTemplate.

Method Summary

Modifier and Type	Method and Description
static UriTemplateBuilder	buildFromTemplate(String template) Creates a new UriTemplateBuilder from the template string.
static UriTemplateBuilder	buildFromTemplate(UriTemplate baseTemplate) Creates a new UriTemplateBuilder from a root UriTemplate.
static boolean	containsOperator(String op)
static UriTemplateBuilder	createBuilder() Creates a new UriTemplateBuilder instance.
String	expand() Applies variable substitution the URI Template and returns the expanded URI.
String	expand(Map<String,Object> vars) Expand the URI template using the supplied values
static String	expand(String templateString, Map<String,Object> values) Expands the given template string using the variable replacements in the supplied Map.
String	expandPartial()
static String	expandPartial(String templateString, Map<String,Object> values) Expands the given template string using the variable replacements in the supplied Map.
int	expressionCount() Returns the number of expressions found in this template
static UriTemplate	fromTemplate(String templateString) Creates a new UriTemplate from the template.
static UriTemplateBuilder	fromTemplate(UriTemplate baseTemplate) Creates a new UriTemplate from a root UriTemplate.
Object	get(String variableName) FIXME Comment this
Collection<UriTemplateComponent>	getComponents() Returns the collection of UriTemplateComponent instances found in this template.
Expression[]	getExpressions() Returns an array of Expression instances found in this template.
protected Pattern	getReverseMatchPattern() Returns the
String	getTemplate() Returns the original URI template expression.
Map<String,Object>	getValues() Returns the collection of name/value pairs contained in the instance.
String[]	getVariables() Returns the list of unique variable names, from all Expression's, in this template.
boolean	hasVariable(String variableName) Returns true if the UriTemplate contains the variableName.
protected void	parseTemplateString() Parse the URI template string into the template model.
UriTemplate	set(Map<String,Object> values) Adds the name/value pairs in the supplied Map to the collection of values within this URI template instance.
UriTemplate	set(String variableName, Date value) Sets a Date value into the list of variable substitutions using the default DateFormat.
UriTemplate	set(String variableName, Object value) Sets a value on the URI template expression variable.
UriTemplate	withDefaultDateFormat(DateFormat dateFormat) Deprecated. replaced by withDefaultDateFormat
UriTemplate	withDefaultDateFormat(String dateFormatString)

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_SEPARATOR

public static final String DEFAULT_SEPARATOR

See Also:

Constant Field Values

defaultDateFormat

@Deprecated
protected DateFormat defaultDateFormat

Deprecated. Replaced by defaultDateTimeFormatter

Constructor Detail

UriTemplate

protected UriTemplate(LinkedList<UriTemplateComponent> components)

Create a new UriTemplate.

Parameters:

components -

Method Detail

createBuilder

public static UriTemplateBuilder createBuilder()

Creates a new UriTemplateBuilder instance.

Returns:

the new UriTemplateBuilder

Since:

2.1.2

buildFromTemplate

public static UriTemplateBuilder buildFromTemplate(String template)
                                            throws MalformedUriTemplateException

Creates a new UriTemplateBuilder from the template string.

Parameters:

template -

Returns:

Throws:

MalformedUriTemplateException

Since:

2.0

buildFromTemplate

public static UriTemplateBuilder buildFromTemplate(UriTemplate baseTemplate)
                                            throws MalformedUriTemplateException

Creates a new UriTemplateBuilder from a root UriTemplate. This method will create a new UriTemplate from the base and copy the variables from the base template to the new UriTemplate.

This method is useful when the base template is less volatile than the child expression and you want to merge the two.

Parameters:

baseTemplate -

Returns:

Throws:

MalformedUriTemplateException

Since:

2.0

fromTemplate

public static final UriTemplate fromTemplate(String templateString)
                                      throws MalformedUriTemplateException

Creates a new UriTemplate from the template.

Parameters:

templateString -

Returns:

Throws:

MalformedUriTemplateException

Since:

2.0

fromTemplate

public static UriTemplateBuilder fromTemplate(UriTemplate baseTemplate)
                                       throws MalformedUriTemplateException

Creates a new UriTemplate from a root UriTemplate. This method will create a new UriTemplate from the base and copy the variables from the base template to the new UriTemplate.

This method is useful when the base template is less volatile than the child expression and you want to merge the two.

Parameters:

baseTemplate -

Returns:

Throws:

MalformedUriTemplateException

Since:

1.0

getComponents

public Collection<UriTemplateComponent> getComponents()

Returns the collection of UriTemplateComponent instances found in this template.

Returns:

expressionCount

public int expressionCount()

Returns the number of expressions found in this template

Returns:

getExpressions

public Expression[] getExpressions()

Returns an array of Expression instances found in this template.

Returns:

getVariables

public String[] getVariables()

Returns the list of unique variable names, from all Expression's, in this template.

Returns:

parseTemplateString

protected void parseTemplateString()
                            throws MalformedUriTemplateException

Parse the URI template string into the template model.

Throws:

MalformedUriTemplateException

getReverseMatchPattern

protected Pattern getReverseMatchPattern()

Returns the

Returns:

expand

public static String expand(String templateString,
                            Map<String,Object> values)
                     throws MalformedUriTemplateException,
                            VariableExpansionException

Expands the given template string using the variable replacements in the supplied Map.

Parameters:

templateString -

values -

Returns:

the expanded URI as a String

Throws:

MalformedUriTemplateException

VariableExpansionException

Since:

1.0

expandPartial

public static String expandPartial(String templateString,
                                   Map<String,Object> values)
                            throws MalformedUriTemplateException,
                                   VariableExpansionException

Expands the given template string using the variable replacements in the supplied Map. Expressions without replacements get preserved and still exist in the expanded URI string.

Parameters:

templateString - URI template

values - Replacements

Returns:

The expanded URI as a String

Throws:

MalformedUriTemplateException

VariableExpansionException

expand

public String expand(Map<String,Object> vars)
              throws VariableExpansionException

Expand the URI template using the supplied values

Parameters:

vars - The values that will be used in the expansion

Returns:

the expanded URI as a String

Throws:

VariableExpansionException

Since:

1.0

expand

public String expand()
              throws VariableExpansionException

Applies variable substitution the URI Template and returns the expanded URI.

Returns:

the expanded URI as a String

Throws:

VariableExpansionException

Since:

1.0

expandPartial

public String expandPartial()
                     throws VariableExpansionException

Returns:

Throws:

VariableExpansionException

getTemplate

public String getTemplate()

Returns the original URI template expression.

Returns:

the template string

Since:

1.1.4

getValues

public Map<String,Object> getValues()

Returns the collection of name/value pairs contained in the instance.

Returns:

the name value pairs

Since:

1.0

withDefaultDateFormat

public UriTemplate withDefaultDateFormat(String dateFormatString)

Parameters:

dateFormatString -

Returns:

the date format used to render dates

Since:

1.0

withDefaultDateFormat

@Deprecated
public UriTemplate withDefaultDateFormat(DateFormat dateFormat)

Deprecated. replaced by withDefaultDateFormat

Parameters:

dateFormat -

Returns:

the date format used to render dates

Since:

1.0

set

public UriTemplate set(String variableName,
                       Object value)

Sets a value on the URI template expression variable.

Parameters:

variableName -

value -

Returns:

Since:

1.0

hasVariable

public boolean hasVariable(String variableName)

Returns true if the UriTemplate contains the variableName.

Parameters:

variableName -

Returns:

get

public Object get(String variableName)

FIXME Comment this

Parameters:

variableName -

Returns:

set

public UriTemplate set(String variableName,
                       Date value)

Sets a Date value into the list of variable substitutions using the default DateFormat.

Parameters:

variableName -

value -

Returns:

Since:

1.0

set

public UriTemplate set(Map<String,Object> values)

Adds the name/value pairs in the supplied Map to the collection of values within this URI template instance.

Parameters:

values -

Returns:

Since:

1.0

containsOperator

public static boolean containsOperator(String op)

Parameters:

op -

Returns: