Class UriTemplate
- java.lang.Object
-
- org.glassfish.jersey.uri.UriTemplate
-
- Direct Known Subclasses:
PathTemplate
public class UriTemplate extends java.lang.ObjectA URI template.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static interfaceUriTemplate.TemplateValueStrategyA strategy interface for processing parameters, should be replaced with a JDK 8 one day in the future.
-
Field Summary
Fields Modifier and Type Field Description static java.util.Comparator<UriTemplate>COMPARATOROrder the templates according to JAX-RS specification.static UriTemplateEMPTYThe empty URI template that matches thenullor empty URI path.private static java.lang.String[]EMPTY_VALUESprivate booleanendsWithSlashTrue if the URI template ends in a '/' character.private java.lang.StringnormalizedTemplateThe normalized URI template.private intnumOfCharactersThe number of characters in the regular expression not resulting from conversion of template variables.private intnumOfExplicitRegexesThe number of explicit regular expressions declared for template variables.private intnumOfRegexGroupsThe number of regular expression groups in this pattern.private PatternWithGroupspatternThe pattern generated from the template.private java.lang.StringtemplateThe URI template.private static java.util.regex.PatternTEMPLATE_NAMES_PATTERNThe regular expression for matching URI templates and names.private java.util.List<java.lang.String>templateVariablesThe template variables in the URI template.
-
Constructor Summary
Constructors Modifier Constructor Description privateUriTemplate()Constructor forNULLtemplate.UriTemplate(java.lang.String template)Construct a new URI template.protectedUriTemplate(UriTemplateParser templateParser)Construct a new URI template.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description java.lang.StringcreateURI(java.lang.String... values)Create a URI by substituting any template variables for corresponding template values.java.lang.StringcreateURI(java.lang.String[] values, int offset, int length)Create a URI by substituting any template variables for corresponding template values.static java.lang.StringcreateURI(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.static java.lang.StringcreateURI(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.java.lang.StringcreateURI(java.util.Map<java.lang.String,java.lang.String> values)Create a URI by substituting any template variables for corresponding template values.private static intcreateUriComponent(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.StringcreateURIWithStringValues(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.StringcreateURIWithStringValues(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)static java.lang.StringcreateURIWithStringValues(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.booleanendsWithSlash()Check if the URI template ends in a slash ('/').booleanequals(java.lang.Object o)Equality is calculated from the String of the regular expression generated from the templates.intgetNumberOfExplicitCharacters()Get the number of characters in the regular expression not resulting from conversion of template variables.intgetNumberOfExplicitRegexes()Get the number of explicit regular expressions declared in the template variables.intgetNumberOfRegexGroups()Get the number of regular expression groupsintgetNumberOfTemplateVariables()Get the number of template variables.PatternWithGroupsgetPattern()Get the URI pattern.java.lang.StringgetTemplate()Get the URI template as a String.java.util.List<java.lang.String>getTemplateVariables()Get the list of template variables for the template.inthashCode()Hash code is calculated from String of the regular expression generated from the template.private static PatternWithGroupsinitUriPattern(UriTemplateParser templateParser)Create the URI pattern from a URI template parser.booleanisTemplateVariablePresent(java.lang.String name)Ascertain if a template variable is a member of this template.booleanmatch(java.lang.CharSequence uri, java.util.List<java.lang.String> groupValues)Match a URI against the template.booleanmatch(java.lang.CharSequence uri, java.util.Map<java.lang.String,java.lang.String> templateVariableToValue)Match a URI against the template.static java.net.URInormalize(java.lang.String uri)Normalize the URI by resolve the dot & dot-dot path segments as described in RFC 3986.static java.net.URInormalize(java.net.URI uri)Normalize the URI by resolve the dot & dot-dot path segments as described in RFC 3986.private static booleannotEmpty(java.lang.String string)static java.net.URIrelativize(java.net.URI baseUri, java.net.URI refUri)Relativize URI with respect to a base URI.static java.net.URIresolve(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.URIresolve(java.net.URI baseUri, java.net.URI refUri)Resolve a relative URI reference against a base URI as defined in RFC 3986.private static voidresolveTemplate(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.StringresolveTemplateValues(UriComponent.Type type, java.lang.String template, boolean encode, java.util.Map<java.lang.String,?> _mapValues)Resolves template variables in the giventemplatefrom_mapValues.java.lang.StringtoString()
-
-
-
Field Detail
-
EMPTY_VALUES
private static final java.lang.String[] EMPTY_VALUES
-
COMPARATOR
public static final java.util.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 java.util.regex.Pattern TEMPLATE_NAMES_PATTERN
The regular expression for matching URI templates and names.
-
EMPTY
public static final UriTemplate EMPTY
The empty URI template that matches thenullor empty URI path.
-
template
private final java.lang.String template
The URI template.
-
normalizedTemplate
private final java.lang.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 java.util.List<java.lang.String> templateVariables
The template variables in the URI template.
-
numOfExplicitRegexes
private final int numOfExplicitRegexes
The number of explicit regular expressions declared for template variables.
-
numOfRegexGroups
private final int numOfRegexGroups
The number of regular expression groups in this pattern.
-
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 forNULLtemplate.
-
UriTemplate
public UriTemplate(java.lang.String template) throws java.util.regex.PatternSyntaxException, java.lang.IllegalArgumentExceptionConstruct 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:
java.util.regex.PatternSyntaxException- if the specified regular expression could not be generatedjava.lang.IllegalArgumentException- if the template isnullor an empty string.
-
UriTemplate
protected UriTemplate(UriTemplateParser templateParser) throws java.util.regex.PatternSyntaxException, java.lang.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:
java.util.regex.PatternSyntaxException- if the specified regular expression could not be generatedjava.lang.IllegalArgumentException- if the template isnullor 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
public 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.- Parameters:
baseUri- base URI to be used for resolution.refUri- reference URI string to be resolved against the base URI.- Returns:
- resolved URI.
- Throws:
java.lang.IllegalArgumentException- If the given string violates the URI specification RFC.
-
resolve
public 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.- Parameters:
baseUri- base URI to be used for resolution.refUri- reference URI to be resolved against the base URI.- Returns:
- resolved URI.
-
normalize
public 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. This method provides a workaround for issues withURI.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", whileURI.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:
java.lang.IllegalArgumentException- If the given string violates the URI specification RFC.- See Also:
URI.normalize()
-
normalize
public 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. This method provides a workaround for issues withURI.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", whileURI.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
public static java.net.URI relativize(java.net.URI baseUri, java.net.URI refUri)Relativize URI with respect to a base URI. After the relativization is done, dots in paths of both URIs areresolved.- Parameters:
baseUri- base URI to be used for relativization.refUri- URI to be relativized.- Returns:
- relativized URI.
-
getTemplate
public final java.lang.String getTemplate()
Get the URI template as a String.- Returns:
- the URI template.
-
getPattern
public final PatternWithGroups getPattern()
Get the URI pattern.- Returns:
- the URI pattern.
-
endsWithSlash
public final boolean endsWithSlash()
Check if the URI template ends in a slash ('/').- Returns:
trueif the template ends in a '/', otherwise false.
-
getTemplateVariables
public final java.util.List<java.lang.String> getTemplateVariables()
Get the list of template variables for the template.- Returns:
- the list of template variables.
-
isTemplateVariablePresent
public final boolean isTemplateVariablePresent(java.lang.String name)
Ascertain if a template variable is a member of this template.- Parameters:
name- name The template variable.- Returns:
trueif the template variable is a member of the template, otherwisefalse.
-
getNumberOfExplicitRegexes
public final int getNumberOfExplicitRegexes()
Get the number of explicit regular expressions declared in the template variables.- Returns:
- the number of explicit regular expressions in the template variables.
-
getNumberOfRegexGroups
public final int getNumberOfRegexGroups()
Get the number of regular expression groups- Returns:
- the number of regular expressions groups
-
getNumberOfExplicitCharacters
public 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
public final int getNumberOfTemplateVariables()
Get the number of template variables.- Returns:
- the number of template variables.
-
match
public final boolean match(java.lang.CharSequence uri, java.util.Map<java.lang.String,java.lang.String> templateVariableToValue) throws java.lang.IllegalArgumentExceptionMatch 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:
java.lang.IllegalArgumentException- if the uri or templateVariableToValue is null.
-
match
public final boolean match(java.lang.CharSequence uri, java.util.List<java.lang.String> groupValues) throws java.lang.IllegalArgumentExceptionMatch 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:
java.lang.IllegalArgumentException- if the uri or templateVariableToValue is null.
-
createURI
public final 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.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
public final java.lang.String createURI(java.lang.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 array of template values. The values will be substituted in order of occurrence of unique template variables.- Returns:
- the URI.
-
createURI
public final java.lang.String createURI(java.lang.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 occurrence of unique template variables.offset- the offset into the template value array.length- the length of the template value array.- Returns:
- the URI.
-
resolveTemplate
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.- Parameters:
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.
-
toString
public final java.lang.String toString()
- Overrides:
toStringin classjava.lang.Object
-
hashCode
public final int hashCode()
Hash code is calculated from String of the regular expression generated from the template.- Overrides:
hashCodein classjava.lang.Object- Returns:
- the hash code.
-
equals
public final boolean equals(java.lang.Object o)
Equality is calculated from the String of the regular expression generated from the templates.- Overrides:
equalsin classjava.lang.Object- Parameters:
o- the reference object with which to compare.- Returns:
- true if equals, otherwise false.
-
createURI
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)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- iftrue, 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
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)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- iftrue, 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
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)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- iftrue, 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
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)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- iftrue, 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 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)
-
notEmpty
private static boolean notEmpty(java.lang.String string)
-
createUriComponent
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)
-
resolveTemplateValues
public 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 giventemplatefrom_mapValues. Resolves only these variables which are defined in the_mapValuesleaving other variables unchanged.- Parameters:
type- Type of thetemplate(port, path, query, ...).template- Input uri component to resolve.encode- True if template values from_mapValuesshould 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:
java.lang.IllegalArgumentException- when_mapValuesvalue is null.
-
-