DispatcherServlet
Spring MVC, as many other web frameworks, is designed around the front controller
pattern where a central Servlet
, the DispatcherServlet
, provides a shared algorithm
for request processing, while actual work is performed by configurable delegate components.
This model is flexible and supports diverse workflows.
The DispatcherServlet
, as any Servlet
, needs to be declared and mapped according
to the Servlet specification by using Java configuration or in web.xml
.
In turn, the DispatcherServlet
uses Spring configuration to discover
the delegate components it needs for request mapping, view resolution, exception
handling, and more.
The following example of the Java configuration registers and initializes
the DispatcherServlet
, which is auto-detected by the Servlet container
(see mvc-container-config):
public class MyWebApplicationInitializer implements WebApplicationInitializer {
@Override
public void onStartup(ServletContext servletCxt) {
// Load Spring web application configuration
AnnotationConfigWebApplicationContext ac = new AnnotationConfigWebApplicationContext();
ac.register(AppConfig.class);
ac.refresh();
// Create and register the DispatcherServlet
DispatcherServlet servlet = new DispatcherServlet(ac);
ServletRegistration.Dynamic registration = servletCxt.addServlet("app", servlet);
registration.setLoadOnStartup(1);
registration.addMapping("/app/*");
}
}
class MyWebApplicationInitializer : WebApplicationInitializer {
override fun onStartup(servletCxt: ServletContext) {
// Load Spring web application configuration
val ac = AnnotationConfigWebApplicationContext()
ac.register(AppConfig::class.java)
ac.refresh()
// Create and register the DispatcherServlet
val servlet = DispatcherServlet(ac)
val registration = servletCxt.addServlet("app", servlet)
registration.setLoadOnStartup(1)
registration.addMapping("/app/*")
}
}
In addition to using the ServletContext API directly, you can also extend
AbstractAnnotationConfigDispatcherServletInitializer and override specific methods
(see the example under mvc-servlet-context-hierarchy).
|
The following example of web.xml
configuration registers and initializes the DispatcherServlet
:
<web-app>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/app-context.xml</param-value>
</context-param>
<servlet>
<servlet-name>app</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value></param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>app</servlet-name>
<url-pattern>/app/*</url-pattern>
</servlet-mapping>
</web-app>
Spring Boot follows a different initialization sequence. Rather than hooking into
the lifecycle of the Servlet container, Spring Boot uses Spring configuration to
bootstrap itself and the embedded Servlet container. Filter and Servlet declarations
are detected in Spring configuration and registered with the Servlet container.
For more details, see the
Spring Boot documentation.
|
Context Hierarchy
DispatcherServlet
expects a WebApplicationContext
(an extension of a plain
ApplicationContext
) for its own configuration. WebApplicationContext
has a link to the
ServletContext
and the Servlet
with which it is associated. It is also bound to the ServletContext
such that applications can use static methods on RequestContextUtils
to look up the
WebApplicationContext
if they need access to it.
For many applications, having a single WebApplicationContext
is simple and suffices.
It is also possible to have a context hierarchy where one root WebApplicationContext
is shared across multiple DispatcherServlet
(or other Servlet
) instances, each with
its own child WebApplicationContext
configuration.
See Additional Capabilities of the ApplicationContext
for more on the context hierarchy feature.
The root WebApplicationContext
typically contains infrastructure beans, such as data repositories and
business services that need to be shared across multiple Servlet
instances. Those beans
are effectively inherited and can be overridden (that is, re-declared) in the Servlet-specific
child WebApplicationContext
, which typically contains beans local to the given Servlet
.
The following image shows this relationship:
The following example configures a WebApplicationContext
hierarchy:
public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
@Override
protected Class<?>[] getRootConfigClasses() {
return new Class<?>[] { RootConfig.class };
}
@Override
protected Class<?>[] getServletConfigClasses() {
return new Class<?>[] { App1Config.class };
}
@Override
protected String[] getServletMappings() {
return new String[] { "/app1/*" };
}
}
class MyWebAppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() {
override fun getRootConfigClasses(): Array<Class<*>> {
return arrayOf(RootConfig::class.java)
}
override fun getServletConfigClasses(): Array<Class<*>> {
return arrayOf(App1Config::class.java)
}
override fun getServletMappings(): Array<String> {
return arrayOf("/app1/*")
}
}
If an application context hierarchy is not required, applications can return all
configuration through getRootConfigClasses() and null from getServletConfigClasses() .
|
The following example shows the web.xml
equivalent:
<web-app>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/root-context.xml</param-value>
</context-param>
<servlet>
<servlet-name>app1</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/app1-context.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>app1</servlet-name>
<url-pattern>/app1/*</url-pattern>
</servlet-mapping>
</web-app>
If an application context hierarchy is not required, applications may configure a
“root” context only and leave the contextConfigLocation Servlet parameter empty.
|
Special Bean Types
The DispatcherServlet
delegates to special beans to process requests and render the
appropriate responses. By “special beans” we mean Spring-managed Object
instances that
implement framework contracts. Those usually come with built-in contracts, but
you can customize their properties and extend or replace them.
The following table lists the special beans detected by the DispatcherServlet
:
Bean type | Explanation |
---|---|
|
Map a request to a handler along with a list of
interceptors for pre- and post-processing.
The mapping is based on some criteria, the details of which vary by The two main |
|
Help the |
Strategy to resolve exceptions, possibly mapping them to handlers, to HTML error views, or other targets. See mvc-exceptionhandlers. |
|
Resolve logical |
|
Resolve the |
|
Resolve themes your web application can use — for example, to offer personalized layouts. See mvc-themeresolver. |
|
Abstraction for parsing a multi-part request (for example, browser form file upload) with the help of some multipart parsing library. See mvc-multipart. |
|
Store and retrieve the “input” and the “output” |
Web MVC Config
Applications can declare the infrastructure beans listed in mvc-servlet-special-bean-types
that are required to process requests. The DispatcherServlet
checks the
WebApplicationContext
for each special bean. If there are no matching bean types,
it falls back on the default types listed in
DispatcherServlet.properties
.
In most cases, the mvc-config is the best starting point. It declares the required beans in either Java or XML and provides a higher-level configuration callback API to customize it.
Spring Boot relies on the MVC Java configuration to configure Spring MVC and provides many extra convenient options. |
Servlet Config
In a Servlet 3.0+ environment, you have the option of configuring the Servlet container
programmatically as an alternative or in combination with a web.xml
file. The following
example registers a DispatcherServlet
:
import org.springframework.web.WebApplicationInitializer;
public class MyWebApplicationInitializer implements WebApplicationInitializer {
@Override
public void onStartup(ServletContext container) {
XmlWebApplicationContext appContext = new XmlWebApplicationContext();
appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml");
ServletRegistration.Dynamic registration = container.addServlet("dispatcher", new DispatcherServlet(appContext));
registration.setLoadOnStartup(1);
registration.addMapping("/");
}
}
import org.springframework.web.WebApplicationInitializer
class MyWebApplicationInitializer : WebApplicationInitializer {
override fun onStartup(container: ServletContext) {
val appContext = XmlWebApplicationContext()
appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml")
val registration = container.addServlet("dispatcher", DispatcherServlet(appContext))
registration.setLoadOnStartup(1)
registration.addMapping("/")
}
}
WebApplicationInitializer
is an interface provided by Spring MVC that ensures your
implementation is detected and automatically used to initialize any Servlet 3 container.
An abstract base class implementation of WebApplicationInitializer
named
AbstractDispatcherServletInitializer
makes it even easier to register the
DispatcherServlet
by overriding methods to specify the servlet mapping and the
location of the DispatcherServlet
configuration.
This is recommended for applications that use Java-based Spring configuration, as the following example shows:
public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
@Override
protected Class<?>[] getRootConfigClasses() {
return null;
}
@Override
protected Class<?>[] getServletConfigClasses() {
return new Class<?>[] { MyWebConfig.class };
}
@Override
protected String[] getServletMappings() {
return new String[] { "/" };
}
}
class MyWebAppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() {
override fun getRootConfigClasses(): Array<Class<*>>? {
return null
}
override fun getServletConfigClasses(): Array<Class<*>>? {
return arrayOf(MyWebConfig::class.java)
}
override fun getServletMappings(): Array<String> {
return arrayOf("/")
}
}
If you use XML-based Spring configuration, you should extend directly from
AbstractDispatcherServletInitializer
, as the following example shows:
public class MyWebAppInitializer extends AbstractDispatcherServletInitializer {
@Override
protected WebApplicationContext createRootApplicationContext() {
return null;
}
@Override
protected WebApplicationContext createServletApplicationContext() {
XmlWebApplicationContext cxt = new XmlWebApplicationContext();
cxt.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml");
return cxt;
}
@Override
protected String[] getServletMappings() {
return new String[] { "/" };
}
}
class MyWebAppInitializer : AbstractDispatcherServletInitializer() {
override fun createRootApplicationContext(): WebApplicationContext? {
return null
}
override fun createServletApplicationContext(): WebApplicationContext {
return XmlWebApplicationContext().apply {
setConfigLocation("/WEB-INF/spring/dispatcher-config.xml")
}
}
override fun getServletMappings(): Array<String> {
return arrayOf("/")
}
}
AbstractDispatcherServletInitializer
also provides a convenient way to add Filter
instances and have them be automatically mapped to the DispatcherServlet
, as the
following example shows:
public class MyWebAppInitializer extends AbstractDispatcherServletInitializer {
// ...
@Override
protected Filter[] getServletFilters() {
return new Filter[] {
new HiddenHttpMethodFilter(), new CharacterEncodingFilter() };
}
}
class MyWebAppInitializer : AbstractDispatcherServletInitializer() {
// ...
override fun getServletFilters(): Array<Filter> {
return arrayOf(HiddenHttpMethodFilter(), CharacterEncodingFilter())
}
}
Each filter is added with a default name based on its concrete type and automatically
mapped to the DispatcherServlet
.
The isAsyncSupported
protected method of AbstractDispatcherServletInitializer
provides a single place to enable async support on the DispatcherServlet
and all
filters mapped to it. By default, this flag is set to true
.
Finally, if you need to further customize the DispatcherServlet
itself, you can
override the createDispatcherServlet
method.
Processing
The DispatcherServlet
processes requests as follows:
-
The
WebApplicationContext
is searched for and bound in the request as an attribute that the controller and other elements in the process can use. It is bound by default under theDispatcherServlet.WEB_APPLICATION_CONTEXT_ATTRIBUTE
key. -
The locale resolver is bound to the request to let elements in the process resolve the locale to use when processing the request (rendering the view, preparing data, and so on). If you do not need locale resolving, you do not need the locale resolver.
-
The theme resolver is bound to the request to let elements such as views determine which theme to use. If you do not use themes, you can ignore it.
-
If you specify a multipart file resolver, the request is inspected for multiparts. If multiparts are found, the request is wrapped in a
MultipartHttpServletRequest
for further processing by other elements in the process. See mvc-multipart for further information about multipart handling. -
An appropriate handler is searched for. If a handler is found, the execution chain associated with the handler (preprocessors, postprocessors, and controllers) is executed in order to prepare a model or rendering. Alternatively, for annotated controllers, the response can be rendered (within the
HandlerAdapter
) instead of returning a view. -
If a model is returned, the view is rendered. If no model is returned (maybe due to a preprocessor or postprocessor intercepting the request, perhaps for security reasons), no view is rendered, because the request could already have been fulfilled.
The HandlerExceptionResolver
beans declared in the WebApplicationContext
are used to
resolve exceptions thrown during request processing. Those exception resolvers allow
customizing the logic to address exceptions. See mvc-exceptionhandlers for more details.
The Spring DispatcherServlet
also supports the return of the
last-modification-date
, as specified by the Servlet API. The process of determining
the last modification date for a specific request is straightforward: The
DispatcherServlet
looks up an appropriate handler mapping and tests whether the
handler that is found implements the LastModified
interface. If so, the value of the
long getLastModified(request)
method of the LastModified
interface is returned to
the client.
You can customize individual DispatcherServlet
instances by adding Servlet
initialization parameters (init-param
elements) to the Servlet declaration in the
web.xml
file. The following table lists the supported parameters:
Parameter | Explanation |
---|---|
|
Class that implements |
|
String that is passed to the context instance (specified by |
|
Namespace of the |
|
Whether to throw a By default, this is set to Note that, if default servlet handling is also configured, unresolved requests are always forwarded to the default servlet and a 404 is never raised. |
Interception
All HandlerMapping
implementations support handler interceptors that are useful when
you want to apply specific functionality to certain requests — for example, checking for
a principal. Interceptors must implement HandlerInterceptor
from the
org.springframework.web.servlet
package with three methods that should provide enough
flexibility to do all kinds of pre-processing and post-processing:
-
preHandle(..)
: Before the actual handler is executed -
postHandle(..)
: After the handler is executed -
afterCompletion(..)
: After the complete request has finished
The preHandle(..)
method returns a boolean value. You can use this method to break or
continue the processing of the execution chain. When this method returns true
, the
handler execution chain continues. When it returns false, the DispatcherServlet
assumes the interceptor itself has taken care of requests (and, for example, rendered an
appropriate view) and does not continue executing the other interceptors and the actual
handler in the execution chain.
See mvc-config-interceptors in the section on MVC configuration for examples of how to
configure interceptors. You can also register them directly by using setters on individual
HandlerMapping
implementations.
Note that postHandle
is less useful with @ResponseBody
and ResponseEntity
methods for
which the response is written and committed within the HandlerAdapter
and before
postHandle
. That means it is too late to make any changes to the response, such as adding
an extra header. For such scenarios, you can implement ResponseBodyAdvice
and either
declare it as an mvc-ann-controller-advice bean or configure it directly on
RequestMappingHandlerAdapter
.
Exceptions
If an exception occurs during request mapping or is thrown from a request handler (such as
a @Controller
), the DispatcherServlet
delegates to a chain of HandlerExceptionResolver
beans to resolve the exception and provide alternative handling, which is typically an
error response.
The following table lists the available HandlerExceptionResolver
implementations:
HandlerExceptionResolver |
Description |
---|---|
|
A mapping between exception class names and error view names. Useful for rendering error pages in a browser application. |
Resolves exceptions raised by Spring MVC and maps them to HTTP status codes.
See also alternative |
|
|
Resolves exceptions with the |
|
Resolves exceptions by invoking an |
Chain of Resolvers
You can form an exception resolver chain by declaring multiple HandlerExceptionResolver
beans in your Spring configuration and setting their order
properties as needed.
The higher the order property, the later the exception resolver is positioned.
The contract of HandlerExceptionResolver
specifies that it can return:
-
a
ModelAndView
that points to an error view. -
An empty
ModelAndView
if the exception was handled within the resolver. -
null
if the exception remains unresolved, for subsequent resolvers to try, and, if the exception remains at the end, it is allowed to bubble up to the Servlet container.
The mvc-config automatically declares built-in resolvers for default Spring MVC
exceptions, for @ResponseStatus
annotated exceptions, and for support of
@ExceptionHandler
methods. You can customize that list or replace it.
Container Error Page
If an exception remains unresolved by any HandlerExceptionResolver
and is, therefore,
left to propagate or if the response status is set to an error status (that is, 4xx, 5xx),
Servlet containers can render a default error page in HTML. To customize the default
error page of the container, you can declare an error page mapping in web.xml
.
The following example shows how to do so:
<error-page>
<location>/error</location>
</error-page>
Given the preceding example, when an exception bubbles up or the response has an error status, the
Servlet container makes an ERROR dispatch within the container to the configured URL
(for example, /error
). This is then processed by the DispatcherServlet
, possibly mapping it
to a @Controller
, which could be implemented to return an error view name with a model
or to render a JSON response, as the following example shows:
@RestController
public class ErrorController {
@RequestMapping(path = "/error")
public Map<String, Object> handle(HttpServletRequest request) {
Map<String, Object> map = new HashMap<String, Object>();
map.put("status", request.getAttribute("javax.servlet.error.status_code"));
map.put("reason", request.getAttribute("javax.servlet.error.message"));
return map;
}
}
@RestController
class ErrorController {
@RequestMapping(path = ["/error"])
fun handle(request: HttpServletRequest): Map<String, Any> {
val map = HashMap<String, Any>()
map["status"] = request.getAttribute("javax.servlet.error.status_code")
map["reason"] = request.getAttribute("javax.servlet.error.message")
return map
}
}
The Servlet API does not provide a way to create error page mappings in Java. You can,
however, use both a WebApplicationInitializer and a minimal web.xml .
|
View Resolution
Spring MVC defines the ViewResolver
and View
interfaces that let you render
models in a browser without tying you to a specific view technology. ViewResolver
provides a mapping between view names and actual views. View
addresses the preparation
of data before handing over to a specific view technology.
The following table provides more details on the ViewResolver
hierarchy:
ViewResolver | Description |
---|---|
|
Sub-classes of |
|
Implementation of |
|
Implementation of |
|
Simple implementation of the |
|
Convenient subclass of |
|
Convenient subclass of |
|
Implementation of the |
Handling
You can chain view resolvers by declaring more than one resolver bean and, if necessary, by
setting the order
property to specify ordering. Remember, the higher the order property,
the later the view resolver is positioned in the chain.
The contract of a ViewResolver
specifies that it can return null to indicate that the
view could not be found. However, in the case of JSPs and InternalResourceViewResolver
,
the only way to figure out if a JSP exists is to perform a dispatch through
RequestDispatcher
. Therefore, you must always configure an InternalResourceViewResolver
to be last in the overall order of view resolvers.
Configuring view resolution is as simple as adding ViewResolver
beans to your Spring
configuration. The mvc-config provides a dedicated configuration API for
mvc-config-view-resolvers and for adding logic-less
View Controllers which are useful for HTML template
rendering without controller logic.
Redirecting
The special redirect:
prefix in a view name lets you perform a redirect. The
UrlBasedViewResolver
(and its subclasses) recognize this as an instruction that a
redirect is needed. The rest of the view name is the redirect URL.
The net effect is the same as if the controller had returned a RedirectView
, but now
the controller itself can operate in terms of logical view names. A logical view
name (such as redirect:/myapp/some/resource
) redirects relative to the current
Servlet context, while a name such as redirect:https://myhost.com/some/arbitrary/path
redirects to an absolute URL.
Note that, if a controller method is annotated with the @ResponseStatus
, the annotation
value takes precedence over the response status set by RedirectView
.
Forwarding
You can also use a special forward:
prefix for view names that are
ultimately resolved by UrlBasedViewResolver
and subclasses. This creates an
InternalResourceView
, which does a RequestDispatcher.forward()
.
Therefore, this prefix is not useful with InternalResourceViewResolver
and
InternalResourceView
(for JSPs), but it can be helpful if you use another view
technology but still want to force a forward of a resource to be handled by the
Servlet/JSP engine. Note that you may also chain multiple view resolvers, instead.
Content Negotiation
ContentNegotiatingViewResolver
does not resolve views itself but rather delegates
to other view resolvers and selects the view that resembles the representation requested
by the client. The representation can be determined from the Accept
header or from a
query parameter (for example, "/path?format=pdf"
).
The ContentNegotiatingViewResolver
selects an appropriate View
to handle the request
by comparing the request media types with the media type (also known as
Content-Type
) supported by the View
associated with each of its ViewResolvers
. The
first View
in the list that has a compatible Content-Type
returns the representation
to the client. If a compatible view cannot be supplied by the ViewResolver
chain,
the list of views specified through the DefaultViews
property is consulted. This
latter option is appropriate for singleton Views
that can render an appropriate
representation of the current resource regardless of the logical view name. The Accept
header can include wildcards (for example text/*
), in which case a View
whose
Content-Type
is text/xml
is a compatible match.
See mvc-config-view-resolvers under mvc-config for configuration details.
Locale
Most parts of Spring’s architecture support internationalization, as the Spring web
MVC framework does. DispatcherServlet
lets you automatically resolve messages
by using the client’s locale. This is done with LocaleResolver
objects.
When a request comes in, the DispatcherServlet
looks for a locale resolver and, if it
finds one, it tries to use it to set the locale. By using the RequestContext.getLocale()
method, you can always retrieve the locale that was resolved by the locale resolver.
In addition to automatic locale resolution, you can also attach an interceptor to the handler mapping (see mvc-handlermapping-interceptor for more information on handler mapping interceptors) to change the locale under specific circumstances (for example, based on a parameter in the request).
Locale resolvers and interceptors are defined in the
org.springframework.web.servlet.i18n
package and are configured in your application
context in the normal way. The following selection of locale resolvers is included in
Spring.
Time Zone
In addition to obtaining the client’s locale, it is often useful to know its time zone.
The LocaleContextResolver
interface offers an extension to LocaleResolver
that lets
resolvers provide a richer LocaleContext
, which may include time zone information.
When available, the user’s TimeZone
can be obtained by using the
RequestContext.getTimeZone()
method. Time zone information is automatically used
by any Date/Time Converter
and Formatter
objects that are registered with Spring’s
ConversionService
.
Header Resolver
This locale resolver inspects the accept-language
header in the request that was sent
by the client (for example, a web browser). Usually, this header field contains the locale of
the client’s operating system. Note that this resolver does not support time zone
information.
Cookie Resolver
This locale resolver inspects a Cookie
that might exist on the client to see if a
Locale
or TimeZone
is specified. If so, it uses the specified details. By using the
properties of this locale resolver, you can specify the name of the cookie as well as the
maximum age. The following example defines a CookieLocaleResolver
:
<bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleResolver">
<property name="cookieName" value="clientlanguage"/>
<!-- in seconds. If set to -1, the cookie is not persisted (deleted when browser shuts down) -->
<property name="cookieMaxAge" value="100000"/>
</bean>
The following table describes the properties CookieLocaleResolver
:
Property | Default | Description |
---|---|---|
|
classname + LOCALE |
The name of the cookie |
|
Servlet container default |
The maximum time a cookie persists on the client. If |
|
/ |
Limits the visibility of the cookie to a certain part of your site. When |
Session Resolver
The SessionLocaleResolver
lets you retrieve Locale
and TimeZone
from the
session that might be associated with the user’s request. In contrast to
CookieLocaleResolver
, this strategy stores locally chosen locale settings in the
Servlet container’s HttpSession
. As a consequence, those settings are temporary
for each session and are, therefore, lost when each session terminates.
Note that there is no direct relationship with external session management mechanisms,
such as the Spring Session project. This SessionLocaleResolver
evaluates and
modifies the corresponding HttpSession
attributes against the current HttpServletRequest
.
Locale Interceptor
You can enable changing of locales by adding the LocaleChangeInterceptor
to one of the
HandlerMapping
definitions. It detects a parameter in the request and changes the locale
accordingly, calling the setLocale
method on the LocaleResolver
in the dispatcher’s
application context. The next example shows that calls to all *.view
resources
that contain a parameter named siteLanguage
now changes the locale. So, for example,
a request for the URL, https://www.sf.net/home.view?siteLanguage=nl
, changes the site
language to Dutch. The following example shows how to intercept the locale:
<bean id="localeChangeInterceptor"
class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">
<property name="paramName" value="siteLanguage"/>
</bean>
<bean id="localeResolver"
class="org.springframework.web.servlet.i18n.CookieLocaleResolver"/>
<bean id="urlMapping"
class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
<property name="interceptors">
<list>
<ref bean="localeChangeInterceptor"/>
</list>
</property>
<property name="mappings">
<value>/**/*.view=someController</value>
</property>
</bean>
Themes
You can apply Spring Web MVC framework themes to set the overall look-and-feel of your application, thereby enhancing user experience. A theme is a collection of static resources, typically style sheets and images, that affect the visual style of the application.
Defining a theme
To use themes in your web application, you must set up an implementation of the
org.springframework.ui.context.ThemeSource
interface. The WebApplicationContext
interface extends ThemeSource
but delegates its responsibilities to a dedicated
implementation. By default, the delegate is an
org.springframework.ui.context.support.ResourceBundleThemeSource
implementation that
loads properties files from the root of the classpath. To use a custom ThemeSource
implementation or to configure the base name prefix of the ResourceBundleThemeSource
,
you can register a bean in the application context with the reserved name, themeSource
.
The web application context automatically detects a bean with that name and uses it.
When you use the ResourceBundleThemeSource
, a theme is defined in a simple properties
file. The properties file lists the resources that make up the theme, as the following example shows:
styleSheet=/themes/cool/style.css background=/themes/cool/img/coolBg.jpg
The keys of the properties are the names that refer to the themed elements from view
code. For a JSP, you typically do this using the spring:theme
custom tag, which is
very similar to the spring:message
tag. The following JSP fragment uses the theme
defined in the previous example to customize the look and feel:
<%@ taglib prefix="spring" uri="http://www.springframework.org/tags"%>
<html>
<head>
<link rel="stylesheet" href="<spring:theme code='styleSheet'/>" type="text/css"/>
</head>
<body style="background=<spring:theme code='background'/>">
...
</body>
</html>
By default, the ResourceBundleThemeSource
uses an empty base name prefix. As a result,
the properties files are loaded from the root of the classpath. Thus, you would put the
cool.properties
theme definition in a directory at the root of the classpath (for
example, in /WEB-INF/classes
). The ResourceBundleThemeSource
uses the standard Java
resource bundle loading mechanism, allowing for full internationalization of themes. For
example, we could have a /WEB-INF/classes/cool_nl.properties
that references a special
background image with Dutch text on it.
Resolving Themes
After you define themes, as described in the preceding section,
you decide which theme to use. The DispatcherServlet
looks for a bean named themeResolver
to find out which ThemeResolver
implementation to use. A theme resolver works in much the same
way as a LocaleResolver
. It detects the theme to use for a particular request and can also
alter the request’s theme. The following table describes the theme resolvers provided by Spring:
Class | Description |
---|---|
|
Selects a fixed theme, set by using the |
|
The theme is maintained in the user’s HTTP session. It needs to be set only once for each session but is not persisted between sessions. |
|
The selected theme is stored in a cookie on the client. |
Spring also provides a ThemeChangeInterceptor
that lets theme changes on every
request with a simple request parameter.
Multipart Resolver
MultipartResolver
from the org.springframework.web.multipart
package is a strategy
for parsing multipart requests including file uploads. There is one implementation
based on Commons FileUpload and another
based on Servlet 3.0 multipart request parsing.
To enable multipart handling, you need to declare a MultipartResolver
bean in your
DispatcherServlet
Spring configuration with a name of multipartResolver
.
The DispatcherServlet
detects it and applies it to the incoming request. When a POST with
content-type of multipart/form-data
is received, the resolver parses the content and
wraps the current HttpServletRequest
as MultipartHttpServletRequest
to
provide access to resolved parts in addition to exposing them as request parameters.
Apache Commons FileUpload
To use Apache Commons FileUpload
, you can configure a bean of type
CommonsMultipartResolver
with a name of multipartResolver
. You also need to
have commons-fileupload
as a dependency on your classpath.
Servlet 3.0
Servlet 3.0 multipart parsing needs to be enabled through Servlet container configuration. To do so:
-
In Java, set a
MultipartConfigElement
on the Servlet registration. -
In
web.xml
, add a"<multipart-config>"
section to the servlet declaration.
The following example shows how to set a MultipartConfigElement
on the Servlet registration:
public class AppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
// ...
@Override
protected void customizeRegistration(ServletRegistration.Dynamic registration) {
// Optionally also set maxFileSize, maxRequestSize, fileSizeThreshold
registration.setMultipartConfig(new MultipartConfigElement("/tmp"));
}
}
class AppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() {
// ...
override fun customizeRegistration(registration: ServletRegistration.Dynamic) {
// Optionally also set maxFileSize, maxRequestSize, fileSizeThreshold
registration.setMultipartConfig(MultipartConfigElement("/tmp"))
}
}
Once the Servlet 3.0 configuration is in place, you can add a bean of type
StandardServletMultipartResolver
with a name of multipartResolver
.
Logging
DEBUG-level logging in Spring MVC is designed to be compact, minimal, and human-friendly. It focuses on high-value bits of information that are useful over and over again versus others that are useful only when debugging a specific issue.
TRACE-level logging generally follows the same principles as DEBUG (and, for example, also should not be a fire hose) but can be used for debugging any issue. In addition, some log messages may show a different level of detail at TRACE versus DEBUG.
Good logging comes from the experience of using the logs. If you spot anything that does not meet the stated goals, please let us know.
Sensitive Data
DEBUG and TRACE logging may log sensitive information. This is why request parameters and
headers are masked by default and their logging in full must be enabled explicitly
through the enableLoggingRequestDetails
property on DispatcherServlet
.
The following example shows how to do so by using Java configuration:
public class MyInitializer
extends AbstractAnnotationConfigDispatcherServletInitializer {
@Override
protected Class<?>[] getRootConfigClasses() {
return ... ;
}
@Override
protected Class<?>[] getServletConfigClasses() {
return ... ;
}
@Override
protected String[] getServletMappings() {
return ... ;
}
@Override
protected void customizeRegistration(ServletRegistration.Dynamic registration) {
registration.setInitParameter("enableLoggingRequestDetails", "true");
}
}
class MyInitializer : AbstractAnnotationConfigDispatcherServletInitializer() {
override fun getRootConfigClasses(): Array<Class<*>>? {
return ...
}
override fun getServletConfigClasses(): Array<Class<*>>? {
return ...
}
override fun getServletMappings(): Array<String> {
return ...
}
override fun customizeRegistration(registration: ServletRegistration.Dynamic) {
registration.setInitParameter("enableLoggingRequestDetails", "true")
}
}