AntPathMatcher (Grails 4.0.3)
Date: 2020-04-03

Package: org.grails.io.support

## [Java] Class AntPathMatcher

- org.grails.io.support.AntPathMatcher

- 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

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static java.lang.String` | `DEFAULT_PATH_SEPARATOR` | Default path separator: "/"

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `java.lang.String` | `combine(java.lang.String pattern1, java.lang.String pattern2)` Combines two patterns into a new pattern that is returned.
    `` | `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`.
    `` | `java.lang.String` | `extractPathWithinPattern(java.lang.String pattern, java.lang.String path)` Given a pattern and a full path, determine the pattern-mapped part.
    `` | `java.util.Map<java.lang.String, java.lang.String>` | `extractUriTemplateVariables(java.lang.String pattern, java.lang.String path)`
    `` | `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.
    `` | `boolean` | `isPattern(java.lang.String path)`
    `` | `boolean` | `match(java.lang.String pattern, java.lang.String path)`
    `` | `boolean` | `matchStart(java.lang.String pattern, java.lang.String path)`
    `` | `void` | `setPathSeparator(java.lang.String pathSeparator)` Set the path separator to use for pattern parsing.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class java.lang.Object` | `java.lang.Object#wait(long, int), java.lang.Object#wait(long), 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: "/"

  - ### 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

    - #### 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)

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

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