public class UriTemplate
extends java.lang.Object
Modifier and Type | Class and Description |
---|---|
private static interface |
UriTemplate.TemplateValueStrategy
A strategy interface for processing parameters, should be replaced with
a JDK 8 one day in the future.
|
Modifier and Type | Field and Description |
---|---|
static java.util.Comparator<UriTemplate> |
COMPARATOR
Order the templates according to JAX-RS specification.
|
static UriTemplate |
EMPTY
The empty URI template that matches the
null or empty URI path. |
private static java.lang.String[] |
EMPTY_VALUES |
private boolean |
endsWithSlash
True if the URI template ends in a '/' character.
|
private java.lang.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 int |
numOfRegexGroups
The number of regular expression groups in this pattern.
|
private PatternWithGroups |
pattern
The pattern generated from the template.
|
private java.lang.String |
template
The URI template.
|
private static java.util.regex.Pattern |
TEMPLATE_NAMES_PATTERN
The regular expression for matching URI templates and names.
|
private java.util.List<java.lang.String> |
templateVariables
The template variables in the URI template.
|
Modifier | Constructor and Description |
---|---|
private |
UriTemplate()
Constructor for
NULL template. |
|
UriTemplate(java.lang.String template)
Construct a new URI template.
|
protected |
UriTemplate(UriTemplateParser templateParser)
Construct a new URI template.
|
Modifier and Type | Method and Description |
---|---|
java.lang.String |
createURI(java.util.Map<java.lang.String,java.lang.String> values)
Create a URI by substituting any template variables
for corresponding template values.
|
java.lang.String |
createURI(java.lang.String... values)
Create a URI by substituting any template variables
for corresponding template values.
|
java.lang.String |
createURI(java.lang.String[] values,
int offset,
int length)
Create a URI by substituting any template variables
for corresponding template values.
|
static java.lang.String |
createURI(java.lang.String scheme,
java.lang.String authority,
java.lang.String userInfo,
java.lang.String host,
java.lang.String port,
java.lang.String path,
java.lang.String query,
java.lang.String fragment,
java.util.Map<java.lang.String,?> values,
boolean encode,
boolean encodeSlashInPath)
Construct a URI from the component parts each of which may contain
template variables.
|
static java.lang.String |
createURI(java.lang.String scheme,
java.lang.String authority,
java.lang.String userInfo,
java.lang.String host,
java.lang.String port,
java.lang.String path,
java.lang.String query,
java.lang.String fragment,
java.lang.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 componentType,
java.lang.String template,
java.lang.String[] values,
int valueOffset,
boolean encode,
java.util.Map<java.lang.String,?> _mapValues,
java.lang.StringBuilder b) |
static java.lang.String |
createURIWithStringValues(java.lang.String scheme,
java.lang.String authority,
java.lang.String userInfo,
java.lang.String host,
java.lang.String port,
java.lang.String path,
java.lang.String query,
java.lang.String fragment,
java.util.Map<java.lang.String,?> values,
boolean encode,
boolean encodeSlashInPath)
Construct a URI from the component parts each of which may contain
template variables.
|
static java.lang.String |
createURIWithStringValues(java.lang.String scheme,
java.lang.String authority,
java.lang.String userInfo,
java.lang.String host,
java.lang.String port,
java.lang.String path,
java.lang.String query,
java.lang.String fragment,
java.lang.String[] values,
boolean encode,
boolean encodeSlashInPath)
Construct a URI from the component parts each of which may contain
template variables.
|
private static java.lang.String |
createURIWithStringValues(java.lang.String scheme,
java.lang.String authority,
java.lang.String userInfo,
java.lang.String host,
java.lang.String port,
java.lang.String path,
java.lang.String query,
java.lang.String fragment,
java.lang.String[] values,
boolean encode,
boolean encodeSlashInPath,
java.util.Map<java.lang.String,?> mapValues) |
boolean |
endsWithSlash()
Check if the URI template ends in a slash (
'/' ). |
boolean |
equals(java.lang.Object o)
Equality is calculated from the String of the regular expression
generated from the templates.
|
int |
getNumberOfExplicitCharacters()
Get the number of characters in the regular expression not resulting
from conversion of template variables.
|
int |
getNumberOfExplicitRegexes()
Get the number of explicit regular expressions declared in the template variables.
|
int |
getNumberOfRegexGroups()
Get the number of regular expression groups
|
int |
getNumberOfTemplateVariables()
Get the number of template variables.
|
PatternWithGroups |
getPattern()
Get the URI pattern.
|
java.lang.String |
getTemplate()
Get the URI template as a String.
|
java.util.List<java.lang.String> |
getTemplateVariables()
Get the list of template variables for the template.
|
int |
hashCode()
Hash code 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.
|
boolean |
isTemplateVariablePresent(java.lang.String name)
Ascertain if a template variable is a member of this
template.
|
boolean |
match(java.lang.CharSequence uri,
java.util.List<java.lang.String> groupValues)
Match a URI against the template.
|
boolean |
match(java.lang.CharSequence uri,
java.util.Map<java.lang.String,java.lang.String> templateVariableToValue)
Match a URI against the template.
|
static java.net.URI |
normalize(java.lang.String uri)
Normalize the URI by resolve the dot & dot-dot path segments as described in
RFC 3986.
|
static java.net.URI |
normalize(java.net.URI uri)
Normalize the URI by resolve the dot & dot-dot path segments as described in
RFC 3986.
|
private static boolean |
notEmpty(java.lang.String string) |
static java.net.URI |
relativize(java.net.URI baseUri,
java.net.URI refUri)
Relativize URI with respect to a base URI.
|
static java.net.URI |
resolve(java.net.URI baseUri,
java.lang.String refUri)
Resolve a relative URI reference against a base URI as defined in
RFC 3986.
|
static java.net.URI |
resolve(java.net.URI baseUri,
java.net.URI refUri)
Resolve a relative URI reference against a base URI as defined in
RFC 3986.
|
private static void |
resolveTemplate(java.lang.String normalizedTemplate,
java.lang.StringBuilder builder,
UriTemplate.TemplateValueStrategy valueStrategy)
Build a URI based on the parameters provided by the variable name strategy.
|
static java.lang.String |
resolveTemplateValues(UriComponent.Type type,
java.lang.String template,
boolean encode,
java.util.Map<java.lang.String,?> _mapValues)
Resolves template variables in the given
template from _mapValues . |
java.lang.String |
toString() |
private static final java.lang.String[] EMPTY_VALUES
public static final java.util.Comparator<UriTemplate> COMPARATOR
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.
private static final java.util.regex.Pattern TEMPLATE_NAMES_PATTERN
public static final UriTemplate EMPTY
null
or empty URI path.private final java.lang.String template
private final java.lang.String normalizedTemplate
private final PatternWithGroups pattern
private final boolean endsWithSlash
private final java.util.List<java.lang.String> templateVariables
private final int numOfExplicitRegexes
private final int numOfRegexGroups
private final int numOfCharacters
private UriTemplate()
NULL
template.public UriTemplate(java.lang.String template) throws java.util.regex.PatternSyntaxException, java.lang.IllegalArgumentException
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.
template
- the template.java.util.regex.PatternSyntaxException
- if the specified
regular expression could not be generatedjava.lang.IllegalArgumentException
- if the template is null
or
an empty string.protected UriTemplate(UriTemplateParser templateParser) throws java.util.regex.PatternSyntaxException, java.lang.IllegalArgumentException
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.
templateParser
- the parser to parse the template.java.util.regex.PatternSyntaxException
- if the specified
regular expression could not be generatedjava.lang.IllegalArgumentException
- if the template is null
or
an empty string.private static PatternWithGroups initUriPattern(UriTemplateParser templateParser)
templateParser
- the URI template parser.public static java.net.URI resolve(java.net.URI baseUri, java.lang.String refUri)
baseUri
- base URI to be used for resolution.refUri
- reference URI string to be resolved against the base URI.java.lang.IllegalArgumentException
- If the given string violates the URI specification RFC.public static java.net.URI resolve(java.net.URI baseUri, java.net.URI refUri)
baseUri
- base URI to be used for resolution.refUri
- reference URI to be resolved against the base URI.public static java.net.URI normalize(java.lang.String uri)
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.uri
- the original URI string.java.lang.IllegalArgumentException
- If the given string violates the URI specification RFC.URI.normalize()
public static java.net.URI normalize(java.net.URI uri)
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.uri
- the original URI.URI.normalize()
public static java.net.URI relativize(java.net.URI baseUri, java.net.URI refUri)
resolved
.baseUri
- base URI to be used for relativization.refUri
- URI to be relativized.public final java.lang.String getTemplate()
public final PatternWithGroups getPattern()
public final boolean endsWithSlash()
'/'
).true
if the template ends in a '/', otherwise false.public final java.util.List<java.lang.String> getTemplateVariables()
public final boolean isTemplateVariablePresent(java.lang.String name)
name
- name The template variable.true
if the template variable is a member of the template, otherwise false
.public final int getNumberOfExplicitRegexes()
public final int getNumberOfRegexGroups()
public final int getNumberOfExplicitCharacters()
public final int getNumberOfTemplateVariables()
public final boolean match(java.lang.CharSequence uri, java.util.Map<java.lang.String,java.lang.String> templateVariableToValue) throws java.lang.IllegalArgumentException
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.
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.java.lang.IllegalArgumentException
- if the uri or
templateVariableToValue is null.public final boolean match(java.lang.CharSequence uri, java.util.List<java.lang.String> groupValues) throws java.lang.IllegalArgumentException
If the URI matches against the pattern the capturing group values (if any) will be added to a list passed in as parameter.
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.java.lang.IllegalArgumentException
- if the uri or
templateVariableToValue is null.public final java.lang.String createURI(java.util.Map<java.lang.String,java.lang.String> values)
A URI template variable without a value will be substituted by the empty string.
values
- the map of template variables to template values.public final java.lang.String createURI(java.lang.String... values)
A URI template variable without a value will be substituted by the empty string.
values
- the array of template values. The values will be
substituted in order of occurrence of unique template variables.public final java.lang.String createURI(java.lang.String[] values, int offset, int length)
A URI template variable without a value will be substituted by the empty string.
values
- the array of template values. The values will be
substituted in order of occurrence of unique template variables.offset
- the offset into the template value array.length
- the length of the template value array.private static void resolveTemplate(java.lang.String normalizedTemplate, java.lang.StringBuilder builder, UriTemplate.TemplateValueStrategy valueStrategy)
normalizedTemplate
- normalized URI template. A normalized template is a template without any explicit regular
expressions.builder
- URI string builder to be used.valueStrategy
- The template value producer strategy to use.public final java.lang.String toString()
toString
in class java.lang.Object
public final int hashCode()
hashCode
in class java.lang.Object
public final boolean equals(java.lang.Object o)
equals
in class java.lang.Object
o
- the reference object with which to compare.public static java.lang.String createURI(java.lang.String scheme, java.lang.String authority, java.lang.String userInfo, java.lang.String host, java.lang.String port, java.lang.String path, java.lang.String query, java.lang.String fragment, java.util.Map<java.lang.String,?> values, boolean encode, boolean encodeSlashInPath)
A template values is an Object instance MUST support the toString() method to convert the template value to a String instance.
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.public static java.lang.String createURIWithStringValues(java.lang.String scheme, java.lang.String authority, java.lang.String userInfo, java.lang.String host, java.lang.String port, java.lang.String path, java.lang.String query, java.lang.String fragment, java.util.Map<java.lang.String,?> values, boolean encode, boolean encodeSlashInPath)
A template value is an Object instance that MUST support the toString() method to convert the template value to a String instance.
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.public static java.lang.String createURI(java.lang.String scheme, java.lang.String authority, java.lang.String userInfo, java.lang.String host, java.lang.String port, java.lang.String path, java.lang.String query, java.lang.String fragment, java.lang.Object[] values, boolean encode, boolean encodeSlashInPath)
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.
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.public static java.lang.String createURIWithStringValues(java.lang.String scheme, java.lang.String authority, java.lang.String userInfo, java.lang.String host, java.lang.String port, java.lang.String path, java.lang.String query, java.lang.String fragment, java.lang.String[] values, boolean encode, boolean encodeSlashInPath)
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.private static java.lang.String createURIWithStringValues(java.lang.String scheme, java.lang.String authority, java.lang.String userInfo, java.lang.String host, java.lang.String port, java.lang.String path, java.lang.String query, java.lang.String fragment, java.lang.String[] values, boolean encode, boolean encodeSlashInPath, java.util.Map<java.lang.String,?> mapValues)
private static boolean notEmpty(java.lang.String string)
private static int createUriComponent(UriComponent.Type componentType, java.lang.String template, java.lang.String[] values, int valueOffset, boolean encode, java.util.Map<java.lang.String,?> _mapValues, java.lang.StringBuilder b)
public static java.lang.String resolveTemplateValues(UriComponent.Type type, java.lang.String template, boolean encode, java.util.Map<java.lang.String,?> _mapValues)
template
from _mapValues
. Resolves only these variables which are
defined in the _mapValues
leaving other variables unchanged.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.java.lang.IllegalArgumentException
- when _mapValues
value is null.