AntPathMatcher (Spring Framework 4.3.9.RELEASE API)

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

All Implemented Interfaces:

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.
Since:

16.07.2003

Author:

Alef Arendsen, Juergen Hoeller, Rob Harrop, Arjen Poutsma, Rossen Stoyanchev, Sam Brannen

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`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)`.

Field Summary

Fields
Modifier and Type Field and Description

static String DEFAULT_PATH_SEPARATOR
Default path separator: "/"

Fields
Modifier and Type	Field and Description
`static String`	`DEFAULT_PATH_SEPARATOR` Default path separator: "/"

Constructor Summary

Constructors
Constructor and Description
`AntPathMatcher()` Create a new instance with the `DEFAULT_PATH_SEPARATOR`.
`AntPathMatcher(String pathSeparator)` A convenient, alternative constructor to use with a custom path separator.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail
- DEFAULT_PATH_SEPARATOR
```
public static final String DEFAULT_PATH_SEPARATOR
```
  Default path separator: "/"
  
  See Also:
  
  Constant Field Values

Constructor Detail
- 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.
  
  Parameters:
  
  pathSeparator - the path separator to use, must not be null.
  
  Since:
  
  4.1

Method Detail

setPathSeparator
```
public void setPathSeparator(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.

Since:

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.

Since:

4.0.1

See Also:

getStringMatcher(String)

isPattern
```
public boolean isPattern(String path)
```
Description copied from interface: 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.

Specified by:

isPattern in interface PathMatcher

Parameters:

path - the path String to check

Returns:

true if the given path represents a pattern

match
```
public boolean match(String pattern,
                     String path)
```
Description copied from interface: PathMatcher

Match the given path against the given pattern, according to this PathMatcher's matching strategy.

Specified by:

match in interface PathMatcher

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
```
public boolean matchStart(String pattern,
                          String path)
```
Description copied from interface: 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.

Specified by:

matchStart in interface PathMatcher

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

doMatch
```
protected boolean doMatch(String pattern,
                          String path,
                          boolean fullMatch,
                          Map<String,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

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.

Parameters:

pattern - the pattern to tokenize

Returns:

the tokenized pattern parts

tokenizePath
```
protected String[] tokenizePath(String path)
```
Tokenize the given path String into parts, based on this matcher's settings.

Parameters:

path - the path to tokenize

Returns:

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.

Parameters:

pattern - the pattern to match against (never null)

Returns:

a corresponding AntPathStringMatcher (never null)

See Also:

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.
Specified by:

extractPathWithinPattern in interface PathMatcher

Parameters:

pattern - the path pattern

path - the full path to introspect

Returns:

the pattern-mapped part of the given path (never null)

extractUriTemplateVariables
```
public Map<String,String> extractUriTemplateVariables(String pattern,
                                                      String path)
```
Description copied from interface: 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".

Specified by:

extractUriTemplateVariables in interface PathMatcher

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

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`

Specified by:: combine in interface PathMatcher
Parameters:: pattern1 - the first pattern; pattern2 - the second pattern
Returns:: the combination of the two patterns
Throws:: 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.
ThisComparator 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.
Specified by:

getPatternComparator in interface PathMatcher

Parameters:

path - the full path to use for comparison

Returns:

a comparator capable of sorting patterns in order of explicitness

Class AntPathMatcher

Examples

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_PATH_SEPARATOR

Constructor Detail

AntPathMatcher

AntPathMatcher

Method Detail

setPathSeparator

setCaseSensitive

setTrimTokens

setCachePatterns

isPattern

match

matchStart

doMatch

tokenizePattern

tokenizePath

getStringMatcher

extractPathWithinPattern

extractUriTemplateVariables

combine

Examples

getPatternComparator