AntPathMatcher (Grails 6.0.0)

Package: org.grails.io.support

## [Java] Class AntPathMatcher

- org.grails.io.support.AntPathMatcher

-     public class AntPathMatcher
      extends java.lang.Object

  PathMatcher implementation for Ant-style path patterns. Examples are provided below.

  Part of this mapping code has been kindly borrowed from Apache Ant.

  The mapping matches URLs using the following rules:

  - ? matches one character
  - * matches zero or more characters
  - ** matches zero or more 'directories' in a path

  Some examples:

  - `com/t?st.jsp` - matches `com/test.jsp` but also `com/tast.jsp` or `com/txst.jsp`
  - `com/*.jsp` - matches all `.jsp` files in the `com` directory
  - `com/**/test.jsp` - matches all `test.jsp` files underneath the `com` path
  - `org/springframework/**/*.jsp` - matches all `.jsp` files underneath the `org/springframework` path
  - `org/**/servlet/bla.jsp` - matches `org/springframework/servlet/bla.jsp` but also `org/springframework/testing/servlet/bla.jsp` and `org/servlet/bla.jsp`
  Authors:
    Alef Arendsen
    Juergen Hoeller
    Rob Harrop
    Arjen Poutsma
  Since:
    16.07.2003

- - ### Nested Class Summary

    Nested classes
    Modifiers | Name | Description
    --- | --- | ---
    `static class` | `AntPathMatcher.AntPathStringMatcher` | Package-protected helper class for org.springframework.util.AntPathMatcher.
    `private static class` | `AntPathMatcher.AntPatternComparator` |

  - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static java.lang.String` | `DEFAULT_PATH_SEPARATOR` | Default path separator: "/"
    `private static java.util.regex.Pattern` | `VARIABLE_PATTERN` |
    `private java.lang.String` | `pathSeparator` |

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public java.lang.String` | `combine(java.lang.String pattern1, java.lang.String pattern2)` Combines two patterns into a new pattern that is returned.
    `` | `public static int` | `countOccurrencesOf(java.lang.String str, java.lang.String sub)` Count the occurrences of the substring in string s.
    `` | `protected boolean` | `doMatch(java.lang.String pattern, java.lang.String path, boolean fullMatch, java.util.Map<java.lang.String, java.lang.String> uriTemplateVariables)` Actually match the given `path` against the given `pattern`.
    `` | `public java.lang.String` | `extractPathWithinPattern(java.lang.String pattern, java.lang.String path)` Given a pattern and a full path, determine the pattern-mapped part.
    `` | `public java.util.Map<java.lang.String, java.lang.String>` | `extractUriTemplateVariables(java.lang.String pattern, java.lang.String path)`
    `` | `public java.util.Comparator<java.lang.String>` | `getPatternComparator(java.lang.String path)` Given a full path, returns a java.util.Comparator suitable for sorting patterns in order of explicitness.
    `` | `private boolean` | `hasText(java.lang.String txt)`
    `` | `public boolean` | `isPattern(java.lang.String path)`
    `` | `public boolean` | `match(java.lang.String pattern, java.lang.String path)`
    `` | `public boolean` | `matchStart(java.lang.String pattern, java.lang.String path)`
    `` | `private boolean` | `matchStrings(java.lang.String pattern, java.lang.String str, java.util.Map<java.lang.String, java.lang.String> uriTemplateVariables)` Tests whether or not a string matches against a pattern.
    `` | `public void` | `setPathSeparator(java.lang.String pathSeparator)` Set the path separator to use for pattern parsing.
    `` | `private java.lang.String[]` | `tokenize(java.lang.String pattern)`

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class java.lang.Object` | `java.lang.Object#wait(long), java.lang.Object#wait(long, int), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll()`

- - ### Field Detail

    - #### public static final java.lang.String DEFAULT_PATH_SEPARATOR

      Default path separator: "/"

    - #### private static final java.util.regex.Pattern VARIABLE_PATTERN

    - #### private java.lang.String pathSeparator

  - ### Method Detail

    - #### public java.lang.String combine(java.lang.String pattern1, java.lang.String pattern2)

      Combines two patterns into a new pattern that is returned.

      This implementation simply concatenates the two patterns, unless the first pattern contains a file extension match (such as `*.html`. In that case, the second pattern should be included in the first, or an `IllegalArgumentException` is thrown.

      For example:

      Pattern 1 | Pattern 2 | Result
      --- | --- | ---
      /hotels | `null` | /hotels
      `null` | /hotels | /hotels
      /hotels | /bookings | /hotels/bookings
      /hotels | bookings | /hotels/bookings
      /hotels/* | /bookings | /hotels/bookings
      /hotels/** | /bookings | /hotels/**/bookings
      /hotels | {hotel} | /hotels/{hotel}
      /hotels/* | {hotel} | /hotels/{hotel}
      /hotels/** | {hotel} | /hotels/**/{hotel}
      /*.html | /hotels.html | /hotels.html
      /*.html | /hotels | /hotels.html
      /*.html | /*.txt | IllegalArgumentException

      throws:
        IllegalArgumentException when the two patterns cannot be combined
      Parameters:
        `pattern1` - the first pattern
        `pattern2` - the second pattern
      Returns:
        the combination of the two patterns

    - #### public static int countOccurrencesOf(java.lang.String str, java.lang.String sub)

      Count the occurrences of the substring in string s.

      Parameters:
        `str` - string to search in. Return 0 if this is null.
        `sub` - string to search for. Return 0 if this is null.

    - #### protected boolean doMatch(java.lang.String pattern, java.lang.String path, boolean fullMatch, java.util.Map<java.lang.String, java.lang.String> uriTemplateVariables)

      Actually match the given `path` against the given `pattern`.

      Parameters:
        `pattern` - the pattern to match against
        `path` - the path String to test
        `fullMatch` - whether a full pattern match is required (else a pattern match as far as the given base path goes is sufficient)
      Returns:
        `true` if the supplied `path` matched, `false` if it didn't

    - #### public java.lang.String extractPathWithinPattern(java.lang.String pattern, java.lang.String path)

      Given a pattern and a full path, determine the pattern-mapped part.

      For example:

      - '`/docs/cvs/commit.html`' and '`/docs/cvs/commit.html` -> ''
      - '`/docs/*`' and '`/docs/cvs/commit` -> '`cvs/commit`'
      - '`/docs/cvs/*.html`' and '`/docs/cvs/commit.html` -> '`commit.html`'
      - '`/docs/**`' and '`/docs/cvs/commit` -> '`cvs/commit`'
      - '`/docs/**/*.html`' and '`/docs/cvs/commit.html` -> '`cvs/commit.html`'
      - '`/*.html`' and '`/docs/cvs/commit.html` -> '`docs/cvs/commit.html`'
      - '`*.html`' and '`/docs/cvs/commit.html` -> '`/docs/cvs/commit.html`'
      - '`*`' and '`/docs/cvs/commit.html` -> '`/docs/cvs/commit.html`'

      Assumes that match returns `true` for '`pattern`' and '`path`', but does not enforce this.

    - #### public java.util.Map<java.lang.String, java.lang.String> extractUriTemplateVariables(java.lang.String pattern, java.lang.String path)

    - #### public java.util.Comparator<java.lang.String> getPatternComparator(java.lang.String path)

      Given a full path, returns a java.util.Comparator suitable for sorting patterns in order of explicitness.

      The returned `Comparator` will {

      linkplain:
        java.util.Collections#sort(java.util.List, java.util.Comparator) sort} a list so that more specific patterns (without uri templates or wild cards) come before generic patterns. So given a list with the following patterns:
        1. `/hotels/new`
        2. `/hotels/{hotel}`
        3. `/hotels/*`
        the returned comparator will sort this list so that the order will be as indicated.

        The full path given as parameter is used to test for exact matches. So when the given path is `/hotels/2`, the pattern `/hotels/2` will be sorted before `/hotels/1`.

      Parameters:
        `path` - the full path to use for comparison
      Returns:
        a comparator capable of sorting patterns in order of explicitness

    - #### private boolean hasText(java.lang.String txt)

    - #### public boolean isPattern(java.lang.String path)

    - #### public boolean match(java.lang.String pattern, java.lang.String path)

    - #### public boolean matchStart(java.lang.String pattern, java.lang.String path)

    - #### private boolean matchStrings(java.lang.String pattern, java.lang.String str, java.util.Map<java.lang.String, java.lang.String> uriTemplateVariables)

      Tests whether or not a string matches against a pattern. The pattern may contain two special characters:
      '*' means zero or more characters
      '?' means one and only one character

      Parameters:
        `pattern` - pattern to match against. Must not be `null`.
        `str` - string which must be matched against the pattern. Must not be `null`.
      Returns:
        `true` if the string matches against the pattern, or `false` otherwise.

    - #### public void setPathSeparator(java.lang.String pathSeparator)

      Set the path separator to use for pattern parsing. Default is "/", as in Ant.

    - #### private java.lang.String[] tokenize(java.lang.String pattern)