Class HttpPattern

  • All Implemented Interfaces:
    java.lang.Comparable<HttpPattern>

    public class HttpPattern
    extends java.lang.Object
    implements java.lang.Comparable<HttpPattern>
    A pattern that matches a well-defined set of paths.

    At its simplest, a pattern is a regular URI path, as defined by RFC 3986, Section 3.3. Such a path starts with a forward slash (/) and then continues with zero or more segments separated by forward slashes. An optional forward slash may be located at the end. While it is recommended for segments to contain only the alphanumeric ASCII characters and hyphens to maximize compatibility with various HTTP libraries and frameworks, RFC 3986 explicitly allows the following characters, as well as so-called percent encodings to be used:

     A–Z a–z 0–9 - . _ ~ ! $ & ' ( ) * + , ; = : @
     
    While all these characters are allowed in segments provided to this pattern implementation, percent encodings are not (e.g. %20 as a representation for ASCII space).

    It is frequently useful to allow certain pattern segments to match any segment at their positions in provided paths. For this reason, pattern segments may be qualified as path parameters by adding a hash (#) at the beginning of the segment (e.g. /some/#parameter or /some/other/#parameter/path). When a path is successfully matched against a pattern, any path parameter segments are collected from the path into a path parameter list.

    A pattern may optionally end with a right angle bracket (>) to denote that the pattern is to be considered a prefix. Prefix patterns match all paths with matching segments up until the right angle bracket. When such a prefix pattern is matched successfully against a path, the segments after the prefix is collected into any path parameter list.

    See Also:
    RFC 3986, Section 3.3
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static HttpPattern ROOT
      The root pattern, only matching the "/" path.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(HttpPattern other)
      The purpose of this comparator, which may seem rather arbitrary, is to ensure that pattern lists sorted with it are ordered such that comparing a path to each pattern in order leads to the most specialized pattern first matching the path.
      boolean intersectsWith​(HttpPattern other)
      Determines whether this pattern matches at least some paths that are also matched by the provided other pattern.
      boolean match​(java.lang.String path, int offset, java.util.List<java.lang.String> parameters)
      Matches this pattern against given path, and collects any path parameters into the provided list.
      int nParameters()  
      java.lang.String text()  
      java.lang.String toString()  
      static HttpPattern valueOf​(java.lang.String pattern)
      Produces HttpPattern from given pattern string.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • ROOT

        public static final HttpPattern ROOT
        The root pattern, only matching the "/" path.
    • Method Detail

      • match

        public boolean match​(java.lang.String path,
                             int offset,
                             java.util.List<java.lang.String> parameters)
        Matches this pattern against given path, and collects any path parameters into the provided list.

        Note that List.clear() will be called on the list if any parameter is identified by the pattern in path. Furthermore, even if this method returns false, it may have collected parameters into the provided list before returning.

        If this pattern contains path parameters or is a prefix, any segments matching a path parameter or occurs after the prefix are not validated, and may, therefore, contain invalid path characters, as dictated by RFC 3986.

        Parameters:
        path - Path to match against.
        offset - Offset, from beginning of path, from which to start matching.
        parameters - List to store any pattern path parameters in.
        Returns:
        true only if path matches this pattern.
        See Also:
        HttpPattern, RFC 3986, Section 3.3
      • intersectsWith

        public boolean intersectsWith​(HttpPattern other)
        Determines whether this pattern matches at least some paths that are also matched by the provided other pattern.
        Parameters:
        other - Pattern to compare to.
        Returns:
        true only if this pattern matches some of the paths that the other pattern does.
      • nParameters

        public int nParameters()
        Returns:
        Number of path parameters.
      • text

        public java.lang.String text()
        Returns:
        Text representation of this pattern.
      • valueOf

        public static HttpPattern valueOf​(java.lang.String pattern)
        Produces HttpPattern from given pattern string.

        Valid patterns must start with a forward slash and consist of zero or more segments separated by forward slashes. A segment must not contain percent encodings, but may otherwise consist of any valid path segment character, as defined by RFC 3986. A segment may optionally start with a hash (#) to make it into a path parameter. The last segment may consist only of a right angle bracket (>) to make the pattern into a so-called prefix-pattern.

        Parameters:
        pattern - String to parse.
        Returns:
        New HttpPattern or ROOT if pattern is "/".
        Throws:
        java.lang.IllegalArgumentException - If pattern is invalid.
        See Also:
        HttpPattern, RFC 3986, Section 3.3
      • compareTo

        public int compareTo​(HttpPattern other)
        The purpose of this comparator, which may seem rather arbitrary, is to ensure that pattern lists sorted with it are ordered such that comparing a path to each pattern in order leads to the most specialized pattern first matching the path. A pattern is more specialized than another such only if the subset of paths it can match is smaller than that of another pattern.

        Specified by:
        compareTo in interface java.lang.Comparable<HttpPattern>
      • toString

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