Add documentation about URI variables in AntPathMatcher [SPR-14652]

[spring-projects-issues]

Bob Tiernay opened SPR-14652 and commented

Currently, there is no mention of URI variables / regexes in AntPathMatcher:

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

However, more complicated expressions are possible using regexes within braces:

{name}/submissions/{projectKey:.+}/files/{fileName:.+}/report

This deserves mentioning because it is a very powerful feature that allows one to do things like negative lookahead assertions, etc.

Also, it might be nice to add Javadocs to ViewControllerRegistry#addViewController and ResourceHandlerRegistry#addResourceHandler that mention that regexes are supported. I would expect a lot of Spring MVC users use these methods and are unaware that this is possible (like myself). This could free users from having to bring in third party libs like the urlrewrite filter for a lot of use cases. A common example is HTML5 pushState mode with an angular SPA:

registry.addViewController("/**/{path:[^.]+}").setViewName("forward:/index.html");

which maps all URLs to index.html.

Lastly, it may be worth reviewing the isPattern method to ensure all patterns are covered:

@Override
public boolean isPattern(String path) {
     return (path.indexOf('*') != -1 || path.indexOf('?') != -1);
}

Notice in the above there is no check for a brace character which is one of the valid metacharacters. My concern is that this may not cover patterns such as the following which neither contain '*' nor '?':

/{path:[^.]+}

---

Referenced from: commits a8ba065, f3dae0c

[spring-projects-issues]

Brian Clozel commented

Thanks Bob Tiernay for raising this. I've added documentation in the places you suggested.

I've tried changing the isPattern method implementation, but this lead to a regression in our test suite (ResourceArrayPropertyEditorTests. testSystemPropertyReplacement(). Because AntPathMatcher is used in many places, sometimes in unexpected ways, even the slightest change can cause issues.

If you find a concrete case (URL mapping) that looks like it, please file a new ticket and we'll look into it.