PathMatcher (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.util

## Interface PathMatcher

- All Known Implementing Classes:
    AntPathMatcher

      public interface PathMatcher

  Strategy interface for `String`-based path matching.

  Used by `PathMatchingResourcePatternResolver`, `AbstractUrlHandlerMapping`, `PropertiesMethodNameResolver`, and `WebContentInterceptor`.

  The default implementation is `AntPathMatcher`, supporting the Ant-style pattern syntax.

  Since:
    1.2
  Author:
    Juergen Hoeller
  See Also:
    `AntPathMatcher`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `combine(String pattern1, String pattern2)` Combines two patterns into a new pattern that is returned.
    `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 for that path.
    `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.

- - ### Method Detail

    - #### isPattern

          boolean isPattern(String path)

      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 `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.

      Parameters:
        `path` - the path String to check
      Returns:
        `true` if the given `path` represents a pattern

    - #### match

          boolean match(String pattern,
                      String path)

      Match the given `path` against the given `pattern`, according to this PathMatcher's matching strategy.
      Parameters:
        `pattern` - the pattern to match against
        `path` - the path String to test
      Returns:
        `true` if the supplied `path` matched, `false` if it didn't

    - #### matchStart

          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.

      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.

      Parameters:
        `pattern` - the pattern to match against
        `path` - the path String to test
      Returns:
        `true` if the supplied `path` matched, `false` if it didn't

    - #### extractPathWithinPattern

          String extractPathWithinPattern(String pattern,
                                        String path)

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

      This method is supposed to find out which part of the path is matched dynamically through an actual pattern, that is, it strips off a statically defined leading path from the given full path, returning only the actually pattern-matched part of the path.

      For example: For "myroot/*.html" as pattern and "myroot/myfile.html" as full path, this method should return "myfile.html". The detailed determination rules are specified to this PathMatcher's matching strategy.

      A simple implementation may return the given full path as-is in case of an actual pattern, and the empty String in case of the pattern not containing any dynamic parts (i.e. the `pattern` parameter being a static path that wouldn't qualify as an actual `pattern`). A sophisticated implementation will differentiate between the static parts and the dynamic parts of the given path pattern.

      Parameters:
        `pattern` - the path pattern
        `path` - the full path to introspect
      Returns:
        the pattern-mapped part of the given `path` (never `null`)

    - #### extractUriTemplateVariables

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

      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".

      Parameters:
        `pattern` - the path pattern, possibly containing URI templates
        `path` - the full path to extract template variables from
      Returns:
        a map, containing variable names as keys; variables values as values

    - #### getPatternComparator

          Comparator<String> getPatternComparator(String path)

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

      The full algorithm used depends on the underlying implementation, but generally, the returned `Comparator` will sort a list so that more specific patterns come before generic patterns.

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

    - #### combine

          String combine(String pattern1,
                       String pattern2)

      Combines two patterns into a new pattern that is returned.

      The full algorithm used for combining the two pattern depends on the underlying implementation.

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