In Spring MVC,
alwaysUseFullPath is a configuration property in
UrlPathHelper and
HandlerMapping implementations that determines whether URL matching relies on the full path within the current servlet context or just the path remaining after the servlet mapping.
How It Works
alwaysUseFullPath=false (Default):
Spring uses the path within the current servlet mapping. If your servlet is mapped to
/app/* and the request is
/app/users/profile, the lookup path used for matching the handlers is
/users/profile.
alwaysUseFullPath=true:
Spring uses the full path within the servlet context. For the same request
/app/users/profile under
/app/*, the lookup path becomes
/app/users/profile.
Why It Matters
Servlet Mappings: It becomes critical when using prefix-based servlet mappings (like
/mapping/*) rather than mapping the
DispatcherServlet to the default root (
/).
Modern Spring: In newer Spring Framework versions, path matching strategies have evolved toward
PathPatternParser, reducing reliance on older
UrlPathHelper configurations.
Changes in Spring 6 and 7
- Since Spring Framework 6.0, handler mappings use parsed patterns (
PathPatternParser) by default. With parsed patterns, setAlwaysUseFullPath() is ignored. Parsed patterns take the servlet path into account only when the servlet is mapped by a path prefix (like /app/*), so a mapping such as @RequestMapping("/example") already matches /app/example without any extra setting.
AbstractHandlerMapping.setAlwaysUseFullPath() has been deprecated since Spring Framework 6.0. As of the Spring Framework 7.0.x API documentation, it is not yet removed, but it has no effect unless you opt out of parsed patterns.- The methods that replaced it,
setUrlPathHelper() and setPathMatcher() (and their getters), are deprecated for removal since Spring Framework 7.0. The reason is that runtime use of UrlPathHelper and PathMatcher in the web modules is being phased out in favor of PathPatternParser.
Example
In this example, we use the default RequestMappingHandlerMapping, which maps requests using the paths declared in @RequestMapping.
Let's map the DispatcherServlet to the /app/* servlet path:
public class AppInitializer extends
AbstractAnnotationConfigDispatcherServletInitializer {
@Override
protected Class<?>[] getRootConfigClasses() {
return null;
}
@Override
protected Class<?>[] getServletConfigClasses() {
return new Class<?>[]{AppConfig.class};
}
@Override
protected String[] getServletMappings() {
return new String[]{"/app/*"};
}
}
Now we will analyze the behavior first with alwaysUseFullPath=false (the default) and then with alwaysUseFullPath=true.
Using alwaysUseFullPath=false (default)
The configuration class:
@EnableWebMvc
@Configuration
@ComponentScan
public class AppConfig {
}
The controller:
@Controller
public class ExampleController {
@RequestMapping("/example")
@ResponseBody
public String handle () {
return "response from ExampleController";
}
}
To try examples, run embedded Jetty (configured in pom.xml of example project below):
mvn jetty:run Output
It works as expected. The servlet path /app is stripped before matching, so @RequestMapping("/example") matches the request to /app/example.
Using alwaysUseFullPath=true
Let's configure RequestMappingHandlerMapping with the desired setting:
@Configuration
@ComponentScan
@EnableWebMvc
public class AppConfig implements WebMvcConfigurer {
@Override
public void configurePathMatch(PathMatchConfigurer configurer) {
UrlPathHelper urlPathHelper = new UrlPathHelper();
urlPathHelper.setAlwaysUseFullPath(true);
configurer.setUrlPathHelper(urlPathHelper);
}
}
Using the same AppInitializer and controller, let's restart the server and access the same URL:
Why can't we access the page anymore? That's because we are now required to always use the full path. The controller's @RequestMapping("/example") now has to include the servlet path, that is, /app/example. Otherwise, no handler is found and the server responds with an error.
Let's modify our controller:
@Controller
public class ExampleController {
@RequestMapping("/app/example")
@ResponseBody
public String handle () {
return "response from ExampleController";
}
}
Let's restart the server without any other changes:
$ curl -s "http://localhost:8080/app/example"
response from ExampleController
The request is now mapped successfully because the handler method is registered with its full path.
Example ProjectDependencies and Technologies Used: - spring-webmvc 7.0.6 (Spring Web MVC)
Version Compatibility: 3.2.9.RELEASE - 7.0.6 Version compatibilities of spring-webmvc with this example: Versions in green have been tested.
- jakarta.servlet-api 6.1.0 (Jakarta Servlet API documentation)
- JDK 25
- Maven 3.9.11
|
