Package org.atmosphere.util.uri

Class UriTemplate

  • public class UriTemplate
extends java.lang.Object
    A URI template.
    Author:
    Paul.Sandoz@Sun.Com

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.Comparator<UriTemplate> COMPARATOR
      Order the templates according according to JAX-RS.
      static UriTemplate EMPTY
      The empty URI template that matches the null or empty URI path

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        UriTemplate​(java.lang.String template)
      Construct a new URI template.
      protected UriTemplate​(UriTemplateParser templateParser)
      Construct a new URI template.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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 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)
      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)
      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.util.Map<java.lang.String,​? extends java.lang.Object> values, boolean encode)
      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 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,​? extends java.lang.Object> values, boolean encode)
      Construct a URI from the component parts each of which may contain template variables.
      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.
      protected UriPattern createUriPattern​(UriTemplateParser templateParser)
      Create the URI pattern from a URI template parser.
      static java.lang.String createURIWithStringValues​(java.lang.String scheme, 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)
      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)
      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.util.Map<java.lang.String,​? extends java.lang.Object> values, boolean encode)
      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 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,​? extends java.lang.Object> values, boolean encode)
      Construct a URI from the component parts each of which may contain template variables.
      UriTemplate destroy()  
      boolean endsWithSlash()  
      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 regexes declared in template variables.
      int getNumberOfTemplateVariables()
      Get the number of template variables.
      UriPattern 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()
      Hashcode is calculated from String of the regular expression generated from the template.
      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.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • COMPARATOR

        public static final java.util.Comparator<UriTemplate> COMPARATOR
        Order the templates according according to JAX-RS.

        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.

      • EMPTY

        public static final UriTemplate EMPTY
        The empty URI template that matches the null or empty URI path

    • Constructor Detail

      • UriTemplate

        public UriTemplate​(java.lang.String template)
            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:
        template - the template.
        Throws:
        java.util.regex.PatternSyntaxException - if the specified regular expression could not be generated
        java.lang.IllegalArgumentException - if the template is null or 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 generated
        java.lang.IllegalArgumentException - if the template is null or an empty string.

    • Method Detail

      • createUriPattern

        protected UriPattern createUriPattern​(UriTemplateParser templateParser)
        Create the URI pattern from a URI template parser.
        Parameters:
        templateParser - the URI template parser.
        Returns:
        the URI pattern.

      • getTemplate

        public final java.lang.String getTemplate()
        Get the URI template as a String.
        Returns:
        the URI template.

      • getPattern

        public final UriPattern getPattern()
        Get the URI pattern.
        Returns:
        the URI pattern.

      • endsWithSlash

        public final boolean endsWithSlash()
        Returns:
        true if 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:
        true if the template variable is a member of the template, otherwise false.

      • getNumberOfExplicitRegexes

        public final int getNumberOfExplicitRegexes()
        Get the number of explicit regexes declared in template variables.
        Returns:
        the number of explicit regexes.

      • 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.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:
        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.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.
        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 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

        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 occurence of unique template variables.
        offset - the offset into the array
        length - the length of the array
        Returns:
        the URI.

      • toString

        public final java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • hashCode

        public final int hashCode()
        Hashcode is calculated from String of the regular expression generated from the template.
        Overrides:
        hashCode in class java.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:
        equals in class java.lang.Object
        Parameters:
        o - the reference object with which to compare.
        Returns:
        true if equals, otherwise false.

      • createURI

        public static final java.lang.String createURI​(java.lang.String scheme,
                                               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,​? extends java.lang.Object> values,
                                               boolean encode)
        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
        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 componnet
        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
        Returns:
        a URI

      • createURI

        public static final 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,​? extends java.lang.Object> values,
                                               boolean encode)
        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 componnet
        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
        Returns:
        a URI

      • createURIWithStringValues

        public static final java.lang.String createURIWithStringValues​(java.lang.String scheme,
                                                               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,​? extends java.lang.Object> values,
                                                               boolean encode)
        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
        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 componnet
        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
        Returns:
        a URI

      • createURIWithStringValues

        public static final 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,​? extends java.lang.Object> values,
                                                               boolean encode)
        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 componnet
        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
        Returns:
        a URI

      • createURI

        public static final java.lang.String createURI​(java.lang.String scheme,
                                               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)
        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
        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 componnet
        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
        Returns:
        a URI

      • createURI

        public static final 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)
        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 componnet
        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
        Returns:
        a URI

      • createURIWithStringValues

        public static final java.lang.String createURIWithStringValues​(java.lang.String scheme,
                                                               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)
        Construct a URI from the component parts each of which may contain template variables.
        Parameters:
        scheme - the URI scheme 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 componnet
        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
        Returns:
        a URI

      • createURIWithStringValues

        public static final 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)
        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 componnet
        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
        Returns:
        a URI