spring-webmvc

Active contributors: rstoyanchev, Juergen Hoeller, Brian Clozel, Sam Brannen

Purpose

spring-webmvc is Spring's Servlet-based, imperative web framework. It centers on the DispatcherServlet front controller, the @RequestMapping/@Controller annotation model, view resolution (Thymeleaf, FreeMarker, JSP), and the functional RouterFunction API. It runs on any Servlet 5+ container (Tomcat, Jetty, Undertow).

Directory layout

spring-webmvc/
└── src/main/java/org/springframework/web/servlet/
    ├── DispatcherServlet.java                      # the front controller
    ├── HandlerMapping.java                         # interface
    ├── HandlerAdapter.java                         # interface
    ├── HandlerInterceptor.java
    ├── ViewResolver.java
    ├── View.java
    ├── ModelAndView.java
    ├── config/                                     # XML namespace + WebMvcConfigurer
    │   └── annotation/                             # @EnableWebMvc, WebMvcConfigurationSupport
    ├── function/                                   # RouterFunction, HandlerFunction (functional API)
    ├── handler/                                    # AbstractHandlerMapping, exception resolvers
    ├── i18n/                                       # LocaleResolver
    ├── mvc/                                        # @Controller infrastructure
    │   ├── annotation/
    │   ├── method/
    │   │   └── annotation/                         # RequestMappingHandlerMapping/Adapter, etc.
    │   ├── condition/                              # request matching conditions
    │   └── support/
    ├── resource/                                   # static resources, ResourceHandler
    ├── support/                                    # WebApplicationContextUtils, etc.
    ├── tags/                                       # JSP tag library (legacy)
    ├── theme/                                      # ThemeResolver (legacy)
    └── view/                                       # ViewResolver implementations (FreeMarker, Groovy, …)

Key abstractions

Type	File	Role
DispatcherServlet	spring-webmvc/src/main/java/org/springframework/web/servlet/DispatcherServlet.java	Front controller — the entry point for every HTTP request
HandlerMapping	spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerMapping.java	Maps a request to a handler
RequestMappingHandlerMapping	spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestMappingHandlerMapping.java	Discovers @RequestMapping methods
HandlerAdapter	spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerAdapter.java	Invokes a handler regardless of its signature
RequestMappingHandlerAdapter	spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestMappingHandlerAdapter.java	Invokes annotated controller methods
HandlerInterceptor	spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.java	Pre/post-handler hook
HandlerExceptionResolver	spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerExceptionResolver.java	Converts handler exceptions to responses
RouterFunction / HandlerFunction	spring-webmvc/src/main/java/org/springframework/web/servlet/function/	Functional alternative to @Controller
WebMvcConfigurer	spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/WebMvcConfigurer.java	User-supplied callbacks for customization
@EnableWebMvc	spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/EnableWebMvc.java	Imports the default MVC configuration

How it works

Request lifecycle

sequenceDiagram
    participant Client
    participant DS as DispatcherServlet
    participant HM as HandlerMapping
    participant Inter as Interceptors
    participant HA as HandlerAdapter
    participant Ctrl as Controller
    participant VR as ViewResolver
    participant V as View
    Client->>DS: HTTP request
    DS->>HM: getHandler(req)
    HM-->>DS: HandlerExecutionChain
    DS->>Inter: preHandle
    DS->>HA: handle(req, res, handler)
    HA->>Ctrl: invoke method (resolve args)
    Ctrl-->>HA: return value (object or ModelAndView)
    HA-->>DS: ModelAndView
    DS->>Inter: postHandle
    DS->>VR: resolveViewName
    VR-->>DS: View
    DS->>V: render(model)
    V-->>Client: HTTP response
    DS->>Inter: afterCompletion

@RequestMapping matching

RequestMappingHandlerMapping scans @Controller beans, extracts every @RequestMapping method, and builds a sorted matrix of conditions (path, method, params, headers, content-type, accept). At request time it picks the most specific match.

The matching is broken into RequestCondition objects (one per condition type) which are AND'd together and ranked. This sits in org.springframework.web.servlet.mvc.condition.

Argument resolution

A controller method like String show(@PathVariable Long id, Model model, @RequestBody UserUpdate body) has its arguments resolved by chained HandlerMethodArgumentResolvers:

Resolver	Handles
PathVariableMethodArgumentResolver	@PathVariable
RequestParamMethodArgumentResolver	@RequestParam
RequestBodyMethodArgumentResolver	@RequestBody
ServletRequestMethodArgumentResolver	HttpServletRequest, Locale
ModelAttributeMethodArgumentResolver	@ModelAttribute

Return values flow through HandlerMethodReturnValueHandlers, mirroring the resolver pattern.

Exception handling

Three layers, tried in order:

1. @ExceptionHandler methods on the same controller
2. @ControllerAdvice beans with @ExceptionHandler
3. DefaultHandlerExceptionResolver — built-in handling of framework exceptions

ResponseEntityExceptionHandler is a base class typically extended by user-supplied global exception handlers.

View resolution

If a controller returns a logical view name ("user/profile"), the chain of ViewResolvers converts it to a View instance (Thymeleaf template, JSP file, FreeMarker template, …). For REST endpoints (@RestController/@ResponseBody), view resolution is bypassed and the body is written via HttpMessageConverter.

Customization

WebMvcConfigurer is the user's customization surface:

@Configuration
@EnableWebMvc
public class MvcConfig implements WebMvcConfigurer {
    public void addInterceptors(InterceptorRegistry registry) { ... }
    public void configureMessageConverters(...) { ... }
    public void addCorsMappings(CorsRegistry registry) { ... }
    public void configureContentNegotiation(...) { ... }
    public void addArgumentResolvers(...) { ... }
}

@EnableWebMvc imports WebMvcConfigurationSupport, which registers the default beans. Spring Boot generally avoids @EnableWebMvc and uses auto-configuration instead, so user WebMvcConfigurer beans run on top of Spring Boot's defaults.

Integration points

• Depends on spring-aop, spring-beans, spring-context, spring-web.
• Runs in any Servlet 5+ container.
• Test integration: spring-test's MockMvc exercises the dispatcher without a real server.

Entry points for modification

• New HandlerMapping — Subclass AbstractHandlerMapping for path-based mapping; RequestMappingHandlerMapping for annotation-driven.
• New argument resolver / return value handler — Implement the corresponding interface, register through WebMvcConfigurer.
• Replacing the dispatcher — DispatcherServlet is final-ish but can be overridden. Most customization happens via configuration rather than subclassing.

Notable internals

• OncePerRequestFilter — A common base class for Servlet filters that should not re-run on async dispatches. Lives in spring-web but heavily used here.
• FrameworkServlet — DispatcherServlet's parent; bridges the Servlet lifecycle to the Spring ApplicationContext lifecycle.
• HandlerMethodIntrospector — Caches reflective metadata per controller method; gives big speedups under load.

See also

• spring-web — shared HTTP foundation
• spring-webflux — reactive alternative
• features/web-mvc