org.springframework.util

## 类 AntPathMatcher

- java.lang.Object
- - org.springframework.util.AntPathMatcher

- 所有已实现的接口:
    PathMatcher

      public class AntPathMatcher
      extends Object
      implements PathMatcher

  `PathMatcher` implementation for Ant-style path patterns.

  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
  - `{spring:[a-z]+}` matches the regexp `[a-z]+` as a path variable named "spring"

  ### 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`
  - `com/{filename:\\w+}.jsp` will match `com/test.jsp` and assign the value `test` to the `filename` variable

  Note: a pattern and a path must both be absolute or must both be relative in order for the two to match. Therefore it is recommended that users of this implementation to sanitize patterns in order to prefix them with "/" as it makes sense in the context in which they're used.

  从以下版本开始:
    16.07.2003
  作者:
    Alef Arendsen, Juergen Hoeller, Rob Harrop, Arjen Poutsma, Rossen Stoyanchev, Sam Brannen

- - ### 嵌套类概要

    嵌套类
    限定符和类型 | 类和说明
    --- | ---
    `protected static class` | `AntPathMatcher.AntPathStringMatcher` Tests whether or not a string matches against a pattern via a `Pattern`.
    `protected static class` | `AntPathMatcher.AntPatternComparator` The default `Comparator` implementation returned by `getPatternComparator(String)`.

  - ### 字段概要

    字段
    限定符和类型 | 字段和说明
    --- | ---
    `static String` | `DEFAULT_PATH_SEPARATOR` Default path separator: "/"

  - ### 构造器概要

    构造器
    构造器和说明
    `AntPathMatcher()` Create a new instance with the `DEFAULT_PATH_SEPARATOR`.
    `AntPathMatcher(String pathSeparator)` A convenient, alternative constructor to use with a custom path separator.

  - ### 方法概要

    所有方法 实例方法 具体方法
    限定符和类型 | 方法和说明
    --- | ---
    `String` | `combine(String pattern1, String pattern2)` Combine two patterns into a new pattern.
    `protected boolean` | `doMatch(String pattern, String path, boolean fullMatch, Map<String,String> uriTemplateVariables)` Actually match the given `path` against the given `pattern`.
    `String` | `extractPathWithinPattern(String pattern, String path)` Given a pattern and a full path, determine the pattern-mapped part.
    `Map<String,String>` | `extractUriTemplateVariables(String pattern, String path)` Given a pattern and a full path, extract the URI template variables.
    `Comparator<String>` | `getPatternComparator(String path)` Given a full path, returns a `Comparator` suitable for sorting patterns in order of explicitness.
    `protected AntPathMatcher.AntPathStringMatcher` | `getStringMatcher(String pattern)` Build or retrieve an `AntPathMatcher.AntPathStringMatcher` for the given pattern.
    `boolean` | `isPattern(String path)` Does the given `path` represent a pattern that can be matched by an implementation of this interface?
    `boolean` | `match(String pattern, String path)` Match the given `path` against the given `pattern`, according to this PathMatcher's matching strategy.
    `boolean` | `matchStart(String pattern, String path)` Match the given `path` against the corresponding part of the given `pattern`, according to this PathMatcher's matching strategy.
    `void` | `setCachePatterns(boolean cachePatterns)` Specify whether to cache parsed pattern metadata for patterns passed into this matcher's `match(java.lang.String, java.lang.String)` method.
    `void` | `setCaseSensitive(boolean caseSensitive)` Specify whether to perform pattern matching in a case-sensitive fashion.
    `void` | `setPathSeparator(String pathSeparator)` Set the path separator to use for pattern parsing.
    `void` | `setTrimTokens(boolean trimTokens)` Specify whether to trim tokenized paths and patterns.
    `protected String[]` | `tokenizePath(String path)` Tokenize the given path String into parts, based on this matcher's settings.
    `protected String[]` | `tokenizePattern(String pattern)` Tokenize the given path pattern into parts, based on this matcher's settings.

    - ### 从类继承的方法 java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### 字段详细资料

    - #### DEFAULT_PATH_SEPARATOR

          public static final String DEFAULT_PATH_SEPARATOR

      Default path separator: "/"
      另请参阅:
        常量字段值

  - ### 构造器详细资料

    - #### AntPathMatcher

          public AntPathMatcher()

      Create a new instance with the `DEFAULT_PATH_SEPARATOR`.

    - #### AntPathMatcher

          public AntPathMatcher(String pathSeparator)

      A convenient, alternative constructor to use with a custom path separator.
      参数:
        `pathSeparator` - the path separator to use, must not be `null`.
      从以下版本开始:
        4.1

  - ### 方法详细资料

    - #### setPathSeparator

          public void setPathSeparator(@Nullable
                                       String pathSeparator)

      Set the path separator to use for pattern parsing.

      Default is "/", as in Ant.

    - #### setCaseSensitive

          public void setCaseSensitive(boolean caseSensitive)

      Specify whether to perform pattern matching in a case-sensitive fashion.

      Default is `true`. Switch this to `false` for case-insensitive matching.

      从以下版本开始:
        4.2

    - #### setTrimTokens

          public void setTrimTokens(boolean trimTokens)

      Specify whether to trim tokenized paths and patterns.

      Default is `false`.

    - #### setCachePatterns

          public void setCachePatterns(boolean cachePatterns)

      Specify whether to cache parsed pattern metadata for patterns passed into this matcher's `match(java.lang.String, java.lang.String)` method. A value of `true` activates an unlimited pattern cache; a value of `false` turns the pattern cache off completely.

      Default is for the cache to be on, but with the variant to automatically turn it off when encountering too many patterns to cache at runtime (the threshold is 65536), assuming that arbitrary permutations of patterns are coming in, with little chance for encountering a recurring pattern.

      从以下版本开始:
        4.0.1
      另请参阅:
        `getStringMatcher(String)`

    - #### isPattern

          public boolean isPattern(String path)

      从接口复制的说明: `PathMatcher`
      Does the given `path` represent a pattern that can be matched by an implementation of this interface?

      If the return value is `false`, then the `PathMatcher.match(java.lang.String, java.lang.String)` method does not have to be used because direct equality comparisons on the static path Strings will lead to the same result.

      指定者:
        `isPattern` 在接口中 `PathMatcher`
      参数:
        `path` - the path String to check
      返回:
        `true` if the given `path` represents a pattern

    - #### match

          public boolean match(String pattern,
                               String path)

      从接口复制的说明: `PathMatcher`
      Match the given `path` against the given `pattern`, according to this PathMatcher's matching strategy.
      指定者:
        `match` 在接口中 `PathMatcher`
      参数:
        `pattern` - the pattern to match against
        `path` - the path String to test
      返回:
        `true` if the supplied `path` matched, `false` if it didn't

    - #### matchStart

          public boolean matchStart(String pattern,
                                    String path)

      从接口复制的说明: `PathMatcher`
      Match the given `path` against the corresponding part of the given `pattern`, according to this PathMatcher's matching strategy.

      Determines whether the pattern at least matches as far as the given base path goes, assuming that a full path may then match as well.

      指定者:
        `matchStart` 在接口中 `PathMatcher`
      参数:
        `pattern` - the pattern to match against
        `path` - the path String to test
      返回:
        `true` if the supplied `path` matched, `false` if it didn't

    - #### doMatch

          protected boolean doMatch(String pattern,
                                    String path,
                                    boolean fullMatch,
                                    @Nullable
                                    Map<String,String> uriTemplateVariables)

      Actually match the given `path` against the given `pattern`.
      参数:
        `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)
      返回:
        `true` if the supplied `path` matched, `false` if it didn't

    - #### tokenizePattern

          protected String[] tokenizePattern(String pattern)

      Tokenize the given path pattern into parts, based on this matcher's settings.

      Performs caching based on `setCachePatterns(boolean)`, delegating to `tokenizePath(String)` for the actual tokenization algorithm.

      参数:
        `pattern` - the pattern to tokenize
      返回:
        the tokenized pattern parts

    - #### tokenizePath

          protected String[] tokenizePath(String path)

      Tokenize the given path String into parts, based on this matcher's settings.
      参数:
        `path` - the path to tokenize
      返回:
        the tokenized path parts

    - #### getStringMatcher

          protected AntPathMatcher.AntPathStringMatcher getStringMatcher(String pattern)

      Build or retrieve an `AntPathMatcher.AntPathStringMatcher` for the given pattern.

      The default implementation checks this AntPathMatcher's internal cache (see `setCachePatterns(boolean)`), creating a new AntPathStringMatcher instance if no cached copy is found.

      When encountering too many patterns to cache at runtime (the threshold is 65536), it turns the default cache off, assuming that arbitrary permutations of patterns are coming in, with little chance for encountering a recurring pattern.

      This method may be overridden to implement a custom cache strategy.

      参数:
        `pattern` - the pattern to match against (never `null`)
      返回:
        a corresponding AntPathStringMatcher (never `null`)
      另请参阅:
        `setCachePatterns(boolean)`

    - #### extractPathWithinPattern

          public String extractPathWithinPattern(String pattern,
                                                 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(java.lang.String, java.lang.String)` returns `true` for '`pattern`' and '`path`', but does not enforce this.

      指定者:
        `extractPathWithinPattern` 在接口中 `PathMatcher`
      参数:
        `pattern` - the path pattern
        `path` - the full path to introspect
      返回:
        the pattern-mapped part of the given `path` (never `null`)

    - #### extractUriTemplateVariables

          public Map<String,String> extractUriTemplateVariables(String pattern,
                                                                String path)

      从接口复制的说明: `PathMatcher`
      Given a pattern and a full path, extract the URI template variables. URI template variables are expressed through curly brackets ('{' and '}').

      For example: For pattern "/hotels/{hotel}" and path "/hotels/1", this method will return a map containing "hotel"->"1".

      指定者:
        `extractUriTemplateVariables` 在接口中 `PathMatcher`
      参数:
        `pattern` - the path pattern, possibly containing URI templates
        `path` - the full path to extract template variables from
      返回:
        a map, containing variable names as keys; variables values as values

    - #### combine

          public String combine(String pattern1,
                                String pattern2)

      Combine two patterns into a new pattern.

      This implementation simply concatenates the two patterns, unless the first pattern contains a file extension match (e.g., `*.html`). In that case, the second pattern will be merged into the first. Otherwise, an `IllegalArgumentException` will be thrown.

      ### Examples

      Pattern 1 | Pattern 2 | Result
      --- | --- | ---
      `null` | `null` |
      /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`

      指定者:
        `combine` 在接口中 `PathMatcher`
      参数:
        `pattern1` - the first pattern
        `pattern2` - the second pattern
      返回:
        the combination of the two patterns
      抛出:
        `IllegalArgumentException` - if the two patterns cannot be combined

    - #### getPatternComparator

          public Comparator<String> getPatternComparator(String path)

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

      This`Comparator` will 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`.

      指定者:
        `getPatternComparator` 在接口中 `PathMatcher`
      参数:
        `path` - the full path to use for comparison
      返回:
        a comparator capable of sorting patterns in order of explicitness