de.weltraumschaf.commons.uri

Class UriTemplate

java.lang.Object

de.weltraumschaf.commons.uri.UriTemplate

class UriTemplate
extends Object

A URI template.

Author:

Paul Sandoz, Martin Matula (martin.matula at oracle.com)

Field Summary

Fields

Modifier and Type	Field and Description
(package private) static Comparator<UriTemplate>	COMPARATOR Order the templates according to JAX-RS specification.
(package private) static UriTemplate	EMPTY The empty URI template that matches the null or empty URI path.
private static String[]	EMPTY_VALUES
private boolean	endsWithSlash True if the URI template ends in a '/' character.
private String	normalizedTemplate The normalized URI template.
private int	numOfCharacters The number of characters in the regular expression not resulting from conversion of template variables.
private int	numOfExplicitRegexes The number of explicit regular expressions declared for template variables.
private PatternWithGroups	pattern The pattern generated from the template.
private String	template The URI template.
private static Pattern	TEMPLATE_NAMES_PATTERN The regular expression for matching URI templates and names.
private List<String>	templateVariables The template variables in the URI template.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	UriTemplate() Constructor for NULL template.
(package private)	UriTemplate(String template) Construct a new URI template.
protected	UriTemplate(UriTemplateParser templateParser) Construct a new URI template.

Method Summary

Modifier and Type	Method and Description
(package private) String	createURI(Map<String,String> values) Create a URI by substituting any template variables for corresponding template values.
(package private) String	createURI(String... values) Create a URI by substituting any template variables for corresponding template values.
(package private) String	createURI(String[] values, int offset, int length) Create a URI by substituting any template variables for corresponding template values.
(package private) static String	createURI(String scheme, String authority, String userInfo, String host, String port, String path, String query, String fragment, Map<String,?> values, boolean encode, boolean encodeSlashInPath) Construct a URI from the component parts each of which may contain template variables.
(package private) static String	createURI(String scheme, String authority, String userInfo, String host, String port, String path, String query, String fragment, Object[] values, boolean encode, boolean encodeSlashInPath) Construct a URI from the component parts each of which may contain template variables.
private static int	createURIComponent(UriComponent.Type t, String template, String[] values, int offset, boolean encode, Map<String,?> _mapValues, StringBuilder b)
(package private) static String	createURIWithStringValues(String scheme, String authority, String userInfo, String host, String port, String path, String query, String fragment, Map<String,?> values, boolean encode, boolean encodeSlashInPath) Construct a URI from the component parts each of which may contain template variables.
(package private) static String	createURIWithStringValues(String scheme, String authority, String userInfo, String host, String port, String path, String query, String fragment, String[] values, boolean encode, boolean encodeSlashInPath) Construct a URI from the component parts each of which may contain template variables.
private static String	createURIWithStringValues(String scheme, String authority, String userInfo, String host, String port, String path, String query, String fragment, String[] values, boolean encode, boolean encodeSlashInPath, Map<String,?> mapValues)
(package private) boolean	endsWithSlash() Check if the URI template ends in a slash ('/').
boolean	equals(Object o) Equality is calculated from the String of the regular expression generated from the templates.
(package private) int	getNumberOfExplicitCharacters() Get the number of characters in the regular expression not resulting from conversion of template variables.
(package private) int	getNumberOfExplicitRegexes() Get the number of explicit regexes declared in template variables.
(package private) int	getNumberOfTemplateVariables() Get the number of template variables.
(package private) PatternWithGroups	getPattern() Get the URI pattern.
(package private) String	getTemplate() Get the URI template as a String.
(package private) List<String>	getTemplateVariables() Get the list of template variables for the template.
int	hashCode() Hashcode is calculated from String of the regular expression generated from the template.
private static PatternWithGroups	initUriPattern(UriTemplateParser templateParser) Create the URI pattern from a URI template parser.
(package private) boolean	isTemplateVariablePresent(String name) Ascertain if a template variable is a member of this template.
(package private) boolean	match(CharSequence uri, List<String> groupValues) Match a URI against the template.
(package private) boolean	match(CharSequence uri, Map<String,String> templateVariableToValue) Match a URI against the template.
(package private) static URI	normalize(String uri) Normalize the URI by resolve the dot & dot-dot path segments as described in RFC 3986.
(package private) static URI	normalize(URI uri) Normalize the URI by resolve the dot & dot-dot path segments as described in RFC 3986.
(package private) static URI	relativize(URI baseUri, URI refUri) Relativize URI with respect to a base URI.
(package private) static URI	resolve(URI baseUri, String refUri) Resolve a relative URI reference against a base URI as defined in RFC 3986.
(package private) static URI	resolve(URI baseUri, URI refUri) Resolve a relative URI reference against a base URI as defined in RFC 3986.
(package private) static String	resolveTemplateValues(UriComponent.Type type, String template, boolean encode, Map<String,?> _mapValues) Resolves template variables in the given template from _mapValues.
private static IllegalArgumentException	templateVariableHasNoValue(String tVariable)
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_VALUES

private static String[] EMPTY_VALUES

COMPARATOR

static final Comparator<UriTemplate> COMPARATOR

Order the templates according to JAX-RS specification.

Sort the set of matching resource classes using the number of characters in the regular expression not resulting from template variables as the primary key, the number of matching groups as a secondary key, and the number of explicit regular expression declarations as the tertiary key.

TEMPLATE_NAMES_PATTERN

private static final Pattern TEMPLATE_NAMES_PATTERN

The regular expression for matching URI templates and names.

EMPTY

static final UriTemplate EMPTY

The empty URI template that matches the null or empty URI path.

template

private final String template

The URI template.

normalizedTemplate

private final String normalizedTemplate

The normalized URI template. Any explicit regex are removed to leave the template variables.

pattern

private final PatternWithGroups pattern

The pattern generated from the template.

endsWithSlash

private final boolean endsWithSlash

True if the URI template ends in a '/' character.

templateVariables

private final List<String> templateVariables

The template variables in the URI template.

numOfExplicitRegexes

private final int numOfExplicitRegexes

The number of explicit regular expressions declared for template variables.

numOfCharacters

private final int numOfCharacters

The number of characters in the regular expression not resulting from conversion of template variables.

Constructor Detail

UriTemplate

private UriTemplate()

Constructor for NULL template.

UriTemplate

UriTemplate(String template)
     throws PatternSyntaxException,
            IllegalArgumentException

Construct a new URI template.

The template will be parsed to extract template variables.

A specific regular expression will be generated from the template to match URIs according to the template and map template variables to template values.

Parameters:

template - the template.

Throws:

PatternSyntaxException - if the specified regular expression could not be generated

IllegalArgumentException - if the template is null or an empty string.

UriTemplate

protected UriTemplate(UriTemplateParser templateParser)
               throws PatternSyntaxException,
                      IllegalArgumentException

Construct a new URI template.

The template will be parsed to extract template variables.

A specific regular expression will be generated from the template to match URIs according to the template and map template variables to template values.

Parameters:

templateParser - the parser to parse the template.

Throws:

PatternSyntaxException - if the specified regular expression could not be generated

IllegalArgumentException - if the template is null or an empty string.

Method Detail

initUriPattern

private static PatternWithGroups initUriPattern(UriTemplateParser templateParser)

Create the URI pattern from a URI template parser.

Parameters:

templateParser - the URI template parser.

Returns:

the URI pattern.

resolve

static URI resolve(URI baseUri,
                   String refUri)

Resolve a relative URI reference against a base URI as defined in RFC 3986.

Parameters:

baseUri - base URI to be used for resolution.

refUri - reference URI string to be resolved against the base URI.

Returns:

resolved URI.

Throws:

IllegalArgumentException - If the given string violates the URI specification RFC.

resolve

static URI resolve(URI baseUri,
                   URI refUri)

Resolve a relative URI reference against a base URI as defined in RFC 3986.

Parameters:

baseUri - base URI to be used for resolution.

refUri - reference URI to be resolved against the base URI.

Returns:

resolved URI.

normalize

static URI normalize(String uri)

Normalize the URI by resolve the dot & dot-dot path segments as described in RFC 3986. This method provides a workaround for issues with java.net.URI#normalize() which is not able to properly normalize absolute paths that start with a ".." segment, e.g. "/../a/b" as required by RFC 3986 (according to RFC 3986 the path "/../a/b" should resolve to "/a/b", while URI.normalize() keeps the ".." segment in the URI path.

Parameters:

uri - the original URI string.

Returns:

the URI with dot and dot-dot segments resolved.

Throws:

IllegalArgumentException - If the given string violates the URI specification RFC.

See Also:

URI.normalize()

normalize

static URI normalize(URI uri)

Normalize the URI by resolve the dot & dot-dot path segments as described in RFC 3986. This method provides a workaround for issues with java.net.URI#normalize() which is not able to properly normalize absolute paths that start with a ".." segment, e.g. "/../a/b" as required by RFC 3986 (according to RFC 3986 the path "/../a/b" should resolve to "/a/b", while URI.normalize() keeps the ".." segment in the URI path.

Parameters:

uri - the original URI.

Returns:

the URI with dot and dot-dot segments resolved.

See Also:

URI.normalize()

relativize

static URI relativize(URI baseUri,
                      URI refUri)

Relativize URI with respect to a base URI. After the relativization is done, dots in paths of both URIs are #normalize(java.net.URI) resolved.

Parameters:

baseUri - base URI to be used for relativization.

refUri - URI to be relativized.

Returns:

relativized URI.

getTemplate

final String getTemplate()

Get the URI template as a String.

Returns:

the URI template.

getPattern

final PatternWithGroups getPattern()

Get the URI pattern.

Returns:

the URI pattern.

endsWithSlash

final boolean endsWithSlash()

Check if the URI template ends in a slash ('/').

Returns:

true if the template ends in a '/', otherwise false.

getTemplateVariables

final List<String> getTemplateVariables()

Get the list of template variables for the template.

Returns:

the list of template variables.

isTemplateVariablePresent

final boolean isTemplateVariablePresent(String name)

Ascertain if a template variable is a member of this template.

Parameters:

name - name The template variable.

Returns:

true if the template variable is a member of the template, otherwise false.

getNumberOfExplicitRegexes

final int getNumberOfExplicitRegexes()

Get the number of explicit regexes declared in template variables.

Returns:

the number of explicit regexes.

getNumberOfExplicitCharacters

final int getNumberOfExplicitCharacters()

Get the number of characters in the regular expression not resulting from conversion of template variables.

Returns:

the number of explicit characters

getNumberOfTemplateVariables

final int getNumberOfTemplateVariables()

Get the number of template variables.

Returns:

the number of template variables.

match

final boolean match(CharSequence uri,
                    Map<String,String> templateVariableToValue)
             throws IllegalArgumentException

Match a URI against the template.

If the URI matches against the pattern then the template variable to value map will be filled with template variables as keys and template values as values.

Parameters:

uri - the uri to match against the template.

templateVariableToValue - the map where to put template variables (as keys) and template values (as values). The map is cleared before any entries are put.

Returns:

true if the URI matches the template, otherwise false.

Throws:

IllegalArgumentException - if the uri or templateVariableToValue is null.

match

final boolean match(CharSequence uri,
                    List<String> groupValues)
             throws IllegalArgumentException

Match a URI against the template.

If the URI matches against the pattern the capturing group values (if any) will be added to a list passed in as parameter.

Parameters:

uri - the uri to match against the template.

groupValues - the list to store the values of a pattern's capturing groups is matching is successful. The values are stored in the same order as the pattern's capturing groups.

Returns:

true if the URI matches the template, otherwise false.

Throws:

IllegalArgumentException - if the uri or templateVariableToValue is null.

createURI

final String createURI(Map<String,String> values)

Create a URI by substituting any template variables for corresponding template values.

A URI template variable without a value will be substituted by the empty string.

Parameters:

values - the map of template variables to template values.

Returns:

the URI.

createURI

final String createURI(String... values)

Create a URI by substituting any template variables for corresponding template values.

A URI template varibale without a value will be substituted by the empty string.

Parameters:

values - the array of template values. The values will be substituted in order of occurence of unique template variables.

Returns:

the URI.

createURI

final String createURI(String[] values,
                       int offset,
                       int length)

Create a URI by substituting any template variables for corresponding template values.

A URI template variable without a value will be substituted by the empty string.

Parameters:

values - the array of template values. The values will be substituted in order of occurence of unique template variables.

offset - the offset into the array

length - the length of the array

Returns:

the URI.

toString

public final String toString()

Overrides:

toString in class Object

hashCode

public final int hashCode()

Hashcode is calculated from String of the regular expression generated from the template.

Overrides:

hashCode in class Object

equals

public final boolean equals(Object o)

Equality is calculated from the String of the regular expression generated from the templates.

Overrides:

equals in class Object

createURI

static String createURI(String scheme,
                        String authority,
                        String userInfo,
                        String host,
                        String port,
                        String path,
                        String query,
                        String fragment,
                        Map<String,?> values,
                        boolean encode,
                        boolean encodeSlashInPath)

Construct a URI from the component parts each of which may contain template variables.

A template values is an Object instance MUST support the toString() method to convert the template value to a String instance.

Parameters:

scheme - the URI scheme component.

authority - the URI authority component.

userInfo - the URI user info component.

host - the URI host component.

port - the URI port component.

path - the URI path component.

query - the URI query component.

fragment - the URI fragment component.

values - the template variable to value map.

encode - if true encode a template value according to the correspond component type of the associated template variable, otherwise contextually encode the template value.

encodeSlashInPath - if true, the slash ('/') characters in parameter values will be encoded if the template is placed in the URI path component, otherwise the slash characters will not be encoded in path templates.

Returns:

a URI.

createURIWithStringValues

static String createURIWithStringValues(String scheme,
                                        String authority,
                                        String userInfo,
                                        String host,
                                        String port,
                                        String path,
                                        String query,
                                        String fragment,
                                        Map<String,?> values,
                                        boolean encode,
                                        boolean encodeSlashInPath)

Construct a URI from the component parts each of which may contain template variables.

A template value is an Object instance that MUST support the toString() method to convert the template value to a String instance.

Parameters:

scheme - the URI scheme component.

authority - the URI authority info component.

userInfo - the URI user info component.

host - the URI host component.

port - the URI port component.

path - the URI path component.

query - the URI query component.

fragment - the URI fragment component.

values - the template variable to value map.

encode - if true encode a template value according to the correspond component type of the associated template variable, otherwise contextually encode the template value.

encodeSlashInPath - if true, the slash ('/') characters in parameter values will be encoded if the template is placed in the URI path component, otherwise the slash characters will not be encoded in path templates.

Returns:

a URI.

createURI

static String createURI(String scheme,
                        String authority,
                        String userInfo,
                        String host,
                        String port,
                        String path,
                        String query,
                        String fragment,
                        Object[] values,
                        boolean encode,
                        boolean encodeSlashInPath)

Construct a URI from the component parts each of which may contain template variables.

The template values are an array of Object and each Object instance MUST support the toString() method to convert the template value to a String instance.

Parameters:

scheme - the URI scheme component.

authority - the URI authority component.

userInfo - the URI user info component.

host - the URI host component.

port - the URI port component.

path - the URI path component.

query - the URI query component.

fragment - the URI fragment component.

values - the array of template values.

encode - if true encode a template value according to the correspond component type of the associated template variable, otherwise contextually encode the template value.

encodeSlashInPath - if true, the slash ('/') characters in parameter values will be encoded if the template is placed in the URI path component, otherwise the slash characters will not be encoded in path templates.

Returns:

a URI.

createURIWithStringValues

static String createURIWithStringValues(String scheme,
                                        String authority,
                                        String userInfo,
                                        String host,
                                        String port,
                                        String path,
                                        String query,
                                        String fragment,
                                        String[] values,
                                        boolean encode,
                                        boolean encodeSlashInPath)

Construct a URI from the component parts each of which may contain template variables.

Parameters:

scheme - the URI scheme component.

authority - the URI authority component.

userInfo - the URI user info component.

host - the URI host component.

port - the URI port component.

path - the URI path component.

query - the URI query component.

fragment - the URI fragment component.

values - the array of template values.

encode - if true encode a template value according to the correspond component type of the associated template variable, otherwise contextually encode the template value.

encodeSlashInPath - if true, the slash ('/') characters in parameter values will be encoded if the template is placed in the URI path component, otherwise the slash characters will not be encoded in path templates.

Returns:

a URI.

createURIWithStringValues

private static String createURIWithStringValues(String scheme,
                                                String authority,
                                                String userInfo,
                                                String host,
                                                String port,
                                                String path,
                                                String query,
                                                String fragment,
                                                String[] values,
                                                boolean encode,
                                                boolean encodeSlashInPath,
                                                Map<String,?> mapValues)

createURIComponent

private static int createURIComponent(UriComponent.Type t,
                                      String template,
                                      String[] values,
                                      int offset,
                                      boolean encode,
                                      Map<String,?> _mapValues,
                                      StringBuilder b)

resolveTemplateValues

static String resolveTemplateValues(UriComponent.Type type,
                                    String template,
                                    boolean encode,
                                    Map<String,?> _mapValues)

Resolves template variables in the given template from _mapValues. Resolves only these variables which are defined in the _mapValues leaving other variables unchanged.

Parameters:

type - Type of the template (port, path, query, ...).

template - Input uri component to resolve.

encode - True if template values from _mapValues should be percent encoded.

_mapValues - Map with template variables as keys and template values as values. None of them should be null.

Returns:

String with resolved template variables.

Throws:

IllegalArgumentException - when _mapValues value is null.

templateVariableHasNoValue

private static IllegalArgumentException templateVariableHasNoValue(String tVariable)