The interface HandlerMapping maps requested URLs to handler methods/objects (such as classes annotated with @Controller together with their @RequestMapping-annotated methods).
Definition of HandlerMappingVersion: 7.0.6 package org.springframework.web.servlet;
public interface HandlerMapping {
default boolean usesPathPatterns(); 1
HandlerExecutionChain getHandler(HttpServletRequest request)
throws Exception; 2
}
DispatcherServlet processes one or more HandlerMappings (in a specified order) to forward the request to the mapped handler object. For a request, once a HandlerMapping returns a non-null HandlerExecutionChain instance, it is used for the next step (i.e. invoking the handler), and no further HandlerMapping objects are attempted. According to DispatcherServlet.properties, the following handlers are registered by default:
BeanNameUrlHandlerMapping: Maps from URLs to beans (the controllers) by bean names. This only works if the URL starts with "/"
DefaultAnnotationHandlerMapping: This was a legacy handler mapping that matched URLs to handler classes/methods via the @RequestMapping value element. It was deprecated back in Spring 3.1 in favor of RequestMappingHandlerMapping, and it has since been removed completely (as of Spring Framework 5.0). It is mentioned here only for historical context — a current DispatcherServlet.properties (or an @EnableWebMvc/Spring Boot configuration) will not register it. More info here (archived docs).
RequestMappingHandlerMapping: RequestMappingHandlerMapping is the HandlerMapping implementation that powers Spring MVC's annotation-based controllers. It scans your @Controller (and @RestController) beans, reads the @RequestMapping annotations (and its shortcuts like @GetMapping, @PostMapping, etc.) on their methods, and builds a map from URL patterns (plus HTTP method, headers, params, etc.) to the matching handler method.
RouterFunctionMapping: It routes requests using functional RouterFunction beans instead of @RequestMapping-annotated methods. It detects and composes all RouterFunction beans in the context, matching each request to its handler function. Available in both Spring MVC (since 5.2) and WebFlux.
We can also print all registered handlers during runtime:
package com.logicbig.example;
import org.springframework.beans.factory.BeanFactoryUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.ApplicationContext;
import org.springframework.core.Ordered;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.servlet.HandlerMapping;
import java.util.Comparator;
import java.util.Map;
@Controller
public class TestController {
@Autowired
ApplicationContext context;
@RequestMapping(value = "/test")
@ResponseBody
public String handleRequest() {
Map<String, HandlerMapping> matchingBeans =
BeanFactoryUtils.beansOfTypeIncludingAncestors(
context,
HandlerMapping.class,
true,
false);
matchingBeans
.entrySet()
.stream()
.sorted(Comparator.comparingInt((Map.Entry<String, HandlerMapping> e) ->
((Ordered) e.getValue()).getOrder())
.thenComparing(Map.Entry::getKey))
.forEach(e -> System.out.printf("order:%s %s=%s%n",
((Ordered) e.getValue()).getOrder(),
e.getKey(),
e.getValue().getClass()
.getSimpleName()));
return "response from /test";
}
}
Running The Example
To try examples, run embedded Jetty (configured in pom.xml of example project below):
mvn jetty:run Accessing http://localhost:8080/test will print the list t on the server console:
$ curl -s "http://localhost:8080/test"
response from /test
Server Output
order:-1 routerFunctionMapping=RouterFunctionMapping
order:0 requestMappingHandlerMapping=RequestMappingHandlerMapping
order:2 beanNameHandlerMapping=BeanNameUrlHandlerMapping
The above list differs from DispatcherServlet.properties because we are using @EnableWebMvc in our configuration class:
@EnableWebMvc
@Configuration
@ComponentScan
public class AppConfig {
}
@EnableWebMvc imports all configuration from DelegatingWebMvcConfiguration (a subclass of WebMvcConfigurationSupport). This configuration includes the registration of HandlerMappings. Check out this tutorial as well.
Note that we also printed the order of each handler. DispatcherServlet processes the handlers in the order provided by the Ordered interface (Lower numbers are processed first).
EmptyHandlerMapping (as seen in the above output) is a static nested class inside WebMvcConfigurationSupport whose getHandler() always returns null. It is processed last, if none of the other mappings matched (its order is set to Integer.MAX_VALUE).
Using RequestMappingHandlerMapping
To have RequestMappingHandlerMapping map our handler methods, we need to use the @RequestMapping annotation on the @Controller class. Throughout this series of tutorials, we have mostly been using this same HandlerMapping. The TestController example above also uses this annotation.
Using BeanNameUrlHandlerMapping
This maps requests to controller beans by their bean names. See an example here.
HandlerMapping settings
Since all default HandlerMapping implementations extend AbstractHandlerMapping, they share the following important common properties:
- setInterceptors(Object... interceptors) Sets interceptors to apply to all matched mappings. Supported interceptor types are HandlerInterceptor, WebRequestInterceptor, and MappedInterceptor.
- setOrder(int order) All registered handler mappings are sorted by this order (ascending). The mapping used is the first one that matches.
- setAlwaysUseFullPath(boolean b) If set to true, the application must use the full mapping path, including the part specified by the parent servlet mapping. The default is false. See an example here.
- setDefaultHandler(Object defaultHandler) A default handler to use when this mapping does not match the request. Its default value is null. See an example here.
How to customize a default HandlerMapping?
To customize one of the default HandlerMappings, we can register it as a @Bean using exactly the same name that WebMvcConfigurationSupport uses — but the drawback of this approach is that we have to set all of its properties from scratch. A better approach is to implement WebMvcConfigurer and override the relevant method that configures the HandlerMapping we want (e.g. WebMvcConfigurer#configurePathMatch()); this is also the standard customization point in Spring Boot applications. If neither option works, we can avoid @EnableWebMvc altogether and extend WebMvcConfigurationSupport directly, overriding the @Bean factory methods that create the default HandlerMapping beans. Check out this tutorial too.
Example ProjectDependencies and Technologies Used: - spring-webmvc 7.0.6 (Spring Web MVC)
Version Compatibility: 4.0.0.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
|
