Package org.springframework.web.util.pattern

# Class PathPattern

java.lang.Object
org.springframework.web.util.pattern.PathPattern

All Implemented Interfaces:
  `Comparable<PathPattern>`

public class PathPattern extends Object implements Comparable<PathPattern>
Representation of a parsed path pattern. Includes a chain of path elements for fast matching and accumulates computed state for quick comparison of patterns.

`PathPattern` matches URL paths using the following rules:

- `?` matches one character
- `*` matches zero or more characters within a path segment
- `**` matches zero or more path segments until the end of the path
- `{spring}` matches a path segment and captures it as a variable named "spring"
- `{spring:[a-z]+}` matches the regexp `[a-z]+` against a path segment and captures it as a path variable named "spring"
- `{*spring}` matches zero or more path segments until the end of the path and captures it as a variable named "spring"

Note: In contrast to `AntPathMatcher`, `**` is supported only at the end of a pattern. For example `/pages/{**}` is valid but `/pages/{**}/details` is not. The same applies also to the capturing variant `{*spring}`. The aim is to eliminate ambiguity when comparing patterns for specificity.

### Examples

- `/pages/t?st.html` — matches `/pages/test.html` as well as `/pages/tXst.html` but not `/pages/toast.html`
- `/resources/*.png` — matches all `.png` files in the `resources` directory
- `/resources/**` — matches all files underneath the `/resources/` path, including `/resources/image.png` and `/resources/css/spring.css`
- `/resources/{*path}` — matches all files underneath the `/resources/`, as well as `/resources`, and captures their relative path in a variable named "path"; `/resources/image.png` will match with "path" → "/image.png", and `/resources/css/spring.css` will match with "path" → "/css/spring.css"
- `/resources/{filename:\\w+}.dat` will match `/resources/spring.dat` and assign the value `"spring"` to the `filename` variable

Since:
  5.0
Author:
  Andy Clement, Rossen Stoyanchev
See Also:
  - `PathContainer`

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`PathPattern.PathMatchInfo`
Holder for URI variables and path parameters (matrix variables) extracted based on the pattern for a given matched path.
`static class`
`PathPattern.PathRemainingMatchInfo`
Holder for the result of a match on the start of a pattern.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Comparator<PathPattern>`
`SPECIFICITY_COMPARATOR`
Comparator that sorts patterns by specificity as follows: Null instances are last.

## Method Summary

Modifier and Type
Method
Description
`PathPattern`
`combine(PathPattern otherPattern)`
Combine this pattern with the one given as parameter, returning a new `PathPattern` instance that concatenates or merges both.
`int`
`compareTo(PathPattern otherPattern)`
Compare this pattern with a supplied pattern: return -1,0,+1 if this pattern is more specific, the same or less specific than the supplied pattern.
`boolean`
`equals(Object other)`
`PathContainer`
`extractPathWithinPattern(PathContainer path)`
Determine the pattern-mapped part for the given path.
`String`
`getPatternString()`
Return the original String that was parsed to create this PathPattern.
`int`
`hashCode()`
`boolean`
`hasPatternSyntax()`
Whether the pattern string contains pattern syntax that would require use of `matches(PathContainer)`, or if it is a regular String that could be compared directly to others.
`PathPattern.PathMatchInfo`
`matchAndExtract(PathContainer pathContainer)`
Match this pattern to the given URI path and return extracted URI template variables as well as path parameters (matrix variables).
`boolean`
`matches(PathContainer pathContainer)`
Whether this pattern matches the given path.
`PathPattern.PathRemainingMatchInfo`
`matchStartOfPath(PathContainer pathContainer)`
Match the beginning of the given path and return the remaining portion not covered by this pattern.
`String`
`toString()`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

## Field Details

### SPECIFICITY_COMPARATOR

public static final Comparator<PathPattern> SPECIFICITY_COMPARATOR
Comparator that sorts patterns by specificity as follows:

1. Null instances are last.
2. Catch-all patterns are last.
3. If both patterns are catch-all, consider the length (longer wins).
4. Compare wildcard and captured variable count (lower wins).
5. Consider length (longer wins)

## Method Details

### getPatternString

public String getPatternString()
Return the original String that was parsed to create this PathPattern.

### hasPatternSyntax

public boolean hasPatternSyntax()
Whether the pattern string contains pattern syntax that would require use of `matches(PathContainer)`, or if it is a regular String that could be compared directly to others.

Since:
  5.2

### matches

public boolean matches(PathContainer pathContainer)
Whether this pattern matches the given path.

Parameters:
  `pathContainer` - the candidate path to attempt to match against
Returns:
  `true` if the path matches this pattern

### matchAndExtract

@Nullable public PathPattern.PathMatchInfo matchAndExtract(PathContainer pathContainer)
Match this pattern to the given URI path and return extracted URI template variables as well as path parameters (matrix variables).

Parameters:
  `pathContainer` - the candidate path to attempt to match against
Returns:
  info object with the extracted variables, or `null` for no match

### matchStartOfPath

@Nullable public PathPattern.PathRemainingMatchInfo matchStartOfPath(PathContainer pathContainer)
Match the beginning of the given path and return the remaining portion not covered by this pattern. This is useful for matching nested routes where the path is matched incrementally at each level.

Parameters:
  `pathContainer` - the candidate path to attempt to match against
Returns:
  info object with the match result or `null` for no match

### extractPathWithinPattern

public PathContainer extractPathWithinPattern(PathContainer path)
Determine the pattern-mapped part for the given path.

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

Notes:

- Assumes that `matches(org.springframework.http.server.PathContainer)` returns `true` for the same path but does not enforce this.
- Duplicate occurrences of separators within the returned result are removed
- Leading and trailing separators are removed from the returned result

Parameters:
  `path` - a path that matches this pattern
Returns:
  the subset of the path that is matched by pattern or "" if none of it is matched by pattern elements

### compareTo

public int compareTo(@Nullable PathPattern otherPattern)
Compare this pattern with a supplied pattern: return -1,0,+1 if this pattern is more specific, the same or less specific than the supplied pattern. The aim is to sort more specific patterns first.

Specified by:
  `compareTo` in interface `Comparable<PathPattern>`

### combine

public PathPattern combine(PathPattern otherPattern)
Combine this pattern with the one given as parameter, returning a new `PathPattern` instance that concatenates or merges both. This operation is not commutative, meaning `pattern1.combine(pattern2)` is not equal to `pattern2.combine(pattern1)`.

Combining two "fixed" patterns effectively concatenates them:

- `"/projects" + "/spring-framework" => "/projects/spring-framework"`

Combining a "fixed" pattern with a "matching" pattern concatenates them:

- `"/projects" + "/{project}" => "/projects/{project}"`

Combining a "matching" pattern with a "fixed" pattern merges them:

- `"/projects/*" + "/spring-framework" => "/projects/spring-framework"`
- `"/projects/*.html" + "/spring-framework.html" => "/projects/spring-framework.html"`

Combining two "matching" patterns merges them:

- `"/projects/**" + "/*.html" => "/projects/*.html"`
- `"/projects/*" + "/{project}" => "/projects/{project}"`
- `"/projects/*.html" + "/spring-framework.*" => "/projects/spring-framework.html"`

Note, if a pattern does not end with a "matching" segment, it is considered as a "fixed" one:

- `"/projects/*/releases" + "/{id}" => "/projects/*/releases/{id}"`

Parameters:
  `otherPattern` - the pattern to be combined with the current one
Returns:
  the new `PathPattern` that combines both patterns
Throws:
  `IllegalArgumentException` - if the combination is not allowed

### equals

public boolean equals(@Nullable Object other)

Overrides:
  `equals` in class `Object`

### hashCode

public int hashCode()

Overrides:
  `hashCode` in class `Object`

### toString

public String toString()

Overrides:
  `toString` in class `Object`