15. Web MVC framework

15.1 Introduction to Spring Web MVC framework

The Spring Web model-view-controller (MVC) framework is designed
around a DispatcherServlet that dispatches requests
to handlers, with configurable handler mappings, view resolution, locale
and theme resolution as well as support for uploading files. The default
handler is based on the @Controller and
@RequestMapping annotations, offering a
wide range of flexible handling methods. With the introduction of Spring
3.0, the @Controller mechanism also allows
you to create RESTful Web sites and applications, through the
@PathVariable annotation and other
features.

“Open for extension...”

A key design principle in Spring Web MVC and in Spring in general
is the “Open for extension, closed for
modification” principle.

Some methods in the core classes of Spring Web MVC are marked
final. As a developer you cannot override these
methods to supply your own behavior. This has not been done arbitrarily,
but specifically with this principal in mind.

For an explanation of this principle, refer to Expert
Spring Web MVC and Web Flow by Seth Ladd and others;
specifically see the section "A Look At Design," on page 117 of the
first edition. Alternatively, see

You cannot add advice to final methods when you use Spring MVC.
For example, you cannot add advice to the
AbstractController.setSynchronizeOnSession() method. Refer to
Section 7.6.1, “Understanding AOP proxies” for more information on
AOP proxies and why you cannot add advice to final methods.

In Spring Web MVC you can use any object as a command or
form-backing object; you do not need to implement a framework-specific
interface or base class. Spring's data binding is highly flexible: for
example, it treats type mismatches as validation errors that can be
evaluated by the application, not as system errors. Thus you need not
duplicate your business objects' properties as simple, untyped strings in
your form objects simply to handle invalid submissions, or to convert the
Strings properly. Instead, it is often preferable to bind directly to your
business objects.

Spring's view resolution is extremely flexible. A
Controller implementation can even write
directly to the response stream. Typically, a
ModelAndView instance consists of a view name and a
model Map, which contains bean names and
corresponding objects such as a command or form, which contain reference
data. View name resolution is highly configurable, through bean names, a
properties file, or your own ViewResolver
implementation. The model (the M in MVC) is based on the
Map interface, which allows for the
complete abstraction of the view technology. You can integrate directly
JSP, Velocity, or any other rendering technology. The model
Map is simply transformed into an
appropriate format, such as JSP request attributes or a Velocity template
model.

15.1.1 Features of Spring Web MVC

Spring Web Flow

Spring Web Flow (SWF) aims to be the best solution for the management
of web application page flow.

SWF integrates with existing frameworks like Spring MVC, Struts, and
JSF, in both servlet and portlet environments. If you have a business
process (or processes) that would benefit from a conversational model as
opposed to a purely request model, then SWF may be the solution.

SWF allows you to capture logical page flows as self-contained modules
that are reusable in different situations, and as such is ideal for building
web application modules that guide the user through controlled navigations
that drive business processes.

Clear separation of roles. Each role --
controller, validator, command object, form object, model object,
DispatcherServlet, handler mapping, view
resolver, and so on -- can be fulfilled by a specialized
object.

Powerful and straightforward configuration of both
framework and application classes as JavaBeans. This
configuration capability includes easy referencing across contexts,
such as from web controllers to business objects and
validators.

Adaptability, non-intrusiveness, and
flexibility. Define any controller method signature you
need, possibly using one of the parameter annotations (such as
@RequestParam, @RequestHeader, @PathVariable, and more) for a given
scenario.

Reusable business code, no need
for duplication. Use existing business objects as command
or form objects instead of mirroring them to extend a particular
framework base class.

Customizable binding and validation. Type
mismatches as application-level validation errors that keep the
offending value, localized date and number binding, and so on
instead of String-only form objects with manual parsing and
conversion to business objects.

Customizable locale and theme resolution, support
for JSPs with or without Spring tag library, support for JSTL,
support for Velocity without the need for extra bridges, and so
on.

A simple yet powerful JSP tag library known as the
Spring tag library that provides support for features such as data
binding and themes. The custom tags allow for maximum
flexibility in terms of markup code. For information on the tag
library descriptor, see the appendix entitled Appendix F, spring.tld

A JSP form tag library, introduced in Spring 2.0,
that makes writing forms in JSP pages much easier. For
information on the tag library descriptor, see the appendix entitled
Appendix G, spring-form.tld

Beans whose lifecycle is scoped to the current HTTP
request or HTTP Session.
This is not a specific feature of Spring MVC itself, but rather of
the WebApplicationContext
container(s) that Spring MVC uses. These bean scopes are described
in Section 3.5.4, “Request, session, and global session scopes”

15.1.2 Pluggability of other MVC implementations

Non-Spring MVC implementations are preferable for some projects.
Many teams expect to leverage their existing investment in skills and
tools. A large body of knowledge and experience exist for the Struts
framework. If you can abide Struts' architectural flaws, it can be a
viable choice for the web layer; the same applies to WebWork and other
web MVC frameworks.

If you do not want to use Spring's web MVC, but intend to leverage
other solutions that Spring offers, you can integrate the web MVC
framework of your choice with Spring easily. Simply start up a Spring
root application context through its
ContextLoaderListener, and access it through
its
ServletContext attribute (or Spring's
respective helper method) from within a Struts or WebWork action. No
"plug-ins" are involved, so no dedicated integration is necessary. From
the web layer's point of view, you simply use Spring as a library, with
the root application context instance as the entry point.

Your registered beans and Spring's services can be at your
fingertips even without Spring's Web MVC. Spring does not compete with
Struts or WebWork in this scenario. It simply addresses the many areas
that the pure web MVC frameworks do not, from bean configuration to data
access and transaction handling. So you can enrich your application with
a Spring middle tier and/or data access tier, even if you just want to
use, for example, the transaction abstraction with JDBC or
Hibernate.

15.2 The DispatcherServlet

Spring's web MVC framework is, like many other web MVC frameworks,
request-driven, designed around a central servlet that dispatches requests
to controllers and offers other functionality that facilitates the
development of web applications. Spring's
DispatcherServlet however, does more than just
that. It is completely integrated with the Spring IoC container and as
such allows you to use every other feature that Spring has.

The request processing workflow of the Spring Web MVC
DispatcherServlet is illustrated in the following
diagram. The pattern-savvy reader will recognize that the
DispatcherServlet is an expression of the
“Front Controller” design pattern (this is a pattern that
Spring Web MVC shares with many other leading web frameworks).

The requesting processing workflow in Spring Web MVC
(high level)

The DispatcherServlet is an actual
Servlet (it inherits from the
HttpServlet base class), and as such is declared in
the web.xml of your web application. You need to map
requests that you want the DispatcherServlet to
handle, by using a URL mapping in the same web.xml
file. This is standard J2EE servlet configuration; the following example
shows such a DispatcherServlet declaration and
mapping:

In the preceding example, all requests ending with
.form will be handled by the exampleDispatcherServlet. This is only the first step in
setting up Spring Web MVC. You
now need to configure the various beans used by the Spring Web MVC
framework (over and above the DispatcherServlet
itself).

As detailed in Section 3.13, “Additional Capabilities of the
ApplicationContext”,
ApplicationContext instances in Spring can
be scoped. In the Web MVC framework, each
DispatcherServlet has its own
WebApplicationContext, which inherits all
the beans already defined in the root
WebApplicationContext. These inherited
beans can be overridden in the servlet-specific scope, and you can define
new scope-specific beans local to a given servlet instance.

Context hierarchy in Spring Web MVC

Upon initialization of a DispatcherServlet,
the framework looks
for a file named[servlet-name]-servlet.xml in the
WEB-INF directory of your web application and creates
the beans defined there, overriding the definitions of any beans defined
with the same name in the global scope.

Consider the following DispatcherServlet
servlet configuration (in the web.xml file):

With the above servlet configuration in place, you
will need to have a file called /WEB-INF/golfing-servlet.xml in your
application; this file will contain all of your Spring Web MVC-specific
components (beans). You can change the exact location of this
configuration file through a servlet initialization parameter (see below
for details).

The WebApplicationContext is an
extension of the plain ApplicationContext
that has some extra features necessary for web applications. It differs
from a normal ApplicationContext in that it
is capable of resolving themes (see Section 15.7, “Using themes”),
and that it knows which servlet it is associated with (by having a link to
the ServletContext). The
WebApplicationContext is bound in the
ServletContext, and by using static methods
on the RequestContextUtils class you can always
look up the WebApplicationContext if you
need access to it.

The Spring DispatcherServlet uses special
beans to process requests and render the appropriate views. These beans
are part of Spring Framework. You can configure them in the
WebApplicationContext, just as you
configure any other bean. However, for most beans, sensible defaults are
provided so you initially do not need to configure them. These
beans are described in the following table.

Contains functionality to map exceptions to views or
implement other more complex exception handling code.

After you set up a DispatcherServlet, and a
request comes in for that specific
DispatcherServlet, the
DispatcherServlet starts processing the request 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 the key
DispatcherServlet.WEB_APPLICATION_CONTEXT_ATTRIBUTE.

The locale resolver is bound to the request to enable elements
in the process to 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 it.

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 Section 15.8.2, “Using the
MultipartResolver” 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.

If a model is returned, the view is rendered. If no model is
returned, (may be 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.

Handler exception resolvers that are declared in the
WebApplicationContext pick up exceptions
that are thrown during processing of the request. Using these exception
resolvers allows you to define custom behaviors to address
exceptions.

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. See the
following table for the list of supported parameters.

Table 15.2. DispatcherServlet initialization
parameters

Parameter

Explanation

contextClass

Class that implements
WebApplicationContext, which
instantiates the context used by this servlet. By default, the
XmlWebApplicationContext is used.

contextConfigLocation

String that is passed to the context instance (specified by
contextClass) to indicate where context(s) can
be found. The string consists potentially of multiple strings
(using a comma as a delimiter) to support multiple contexts. In
case of multiple context locations with beans that are defined
twice, the latest location takes precedence.

namespace

Namespace of the
WebApplicationContext. Defaults to
[servlet-name]-servlet.

15.3 Implementing Controllers

Controllers provide access to the application behavior that you
typically define through a service interface. Controllers
interpret user input and transform it into a model that is represented to
the user by the view. Spring implements a controller in a very abstract
way, which enables you to create a wide variety of controllers.

Spring 2.5 introduced an annotation-based programming model for MVC
controllers that uses annotations such as
@RequestMapping,
@RequestParam,
@ModelAttribute, and so on. This annotation
support is available for both Servlet MVC and Portlet MVC. Controllers
implemented in this style do not have to extend specific base classes or
implement specific interfaces. Furthermore, they do not usually have
direct dependencies on Servlet or Portlet APIs, although you can easily
configure access to Servlet or Portlet facilities.

Tip

Available in the samples repository,
the PetClinic web application leverages
the annotation support described in this section, in the context of
simple form processing.

As you can see, the @Controller and
@RequestMapping annotations allow flexible
method names and signatures. In this particular example the method has no
parameters and returns a ModelAndView, but various
other (and better) strategies exist, as
are explained later in this section. ModelAndView,
@Controller, and
@RequestMapping form the basis for the
Spring MVC implementation. This section documents these annotations and
how they are most commonly used in a Servlet environment.

15.3.1 Defining a controller with
@Controller

The @Controller annotation
indicates that a particular class serves the role of a
controller. Spring does not require you to extend
any controller base class or reference the Servlet API. However, you can
still reference Servlet-specific features if you need to.

The @Controller annotation acts as
a stereotype for the annotated class, indicating its role. The
dispatcher scans such annotated classes for mapped methods and detects
@RequestMapping annotations (see the next
section).

You can define annotated controller beans explicitly, using a
standard Spring bean definition in the dispatcher's context. However,
the @Controller stereotype also allows
for autodetection, aligned with Spring general support for detecting
component classes in the classpath and auto-registering bean definitions
for them.

To enable autodetection of such annotated controllers, you add
component scanning to your configuration. Use the
spring-context schema as shown in the following XML
snippet:

In the example, the @RequestMapping
is used in a number of places. The first usage is on the type (class)
level, which indicates that all handling methods on this controller are
relative to the /appointments path. The
get() method has a further
@RequestMapping refinement: it only
accepts GET requests, meaning that an HTTP GET for
/appointments invokes this method. The
post() has a similar refinement, and the
getNewForm() combines the definition of HTTP
method and path into one, so that GET requests for
appointments/new are handled by that method.

The getForDay() method shows another
usage of @RequestMapping: URI templates.
(See the next
section ).

A @RequestMapping on the class
level is not required. Without it, all paths are simply absolute, and
not relative. The following example from the PetClinic sample
application shows a multi-action controller using
@RequestMapping:

A common pitfall when working with annotated controller classes
happens when applying functionality that requires creating a proxy
proxy for the controller object (e.g.
@Transactional methods). Usually you
will introduce an interface for the controller in order to use JDK
dynamic proxies. To make this work you must move the
@RequestMapping annotations to the
interface as as the mapping mechanism can only "see" the interface
exposed by the proxy. As an alternative, you may choose to activate
proxy-target-class="true" in the configuration for the
functionality applied to the controller (in our transaction scenario
in <tx:annotation-driven />). Doing so indicates
that CGLIB-based subclass proxies should be used instead of
interface-based JDK proxies. For more information on various proxying
mechanisms see Section 7.6, “Proxying mechanisms”.

15.3.2.1 URI Templates

To access parts of a request URL in your handling methods, use
the URI templates in the
@RequestMapping path value.

URI Templates

A URI Template is a URI-like string, containing one or more
variable names. When you substitute values for these variables, the
template becomes a URI. The proposed
RFC for URI Templates defines how a URI is parameterized.
For example, the URI Template

http://www.example.com/users/{userid}

contains the variable userid. If we
assign the variable the value fred, the URI Template yields:

http://www.example.com/users/fred

During the processing of a request, the URI can be compared to
an expected URI Template in order to extract a collection of
variables.

Use the @PathVariable method
parameter annotation to indicate that a method parameter should be
bound to the value of a URI template variable.

The following code snippet shows the usage of a single
@PathVariable in a controller
method:

The URI Template "/owners/{ownerId}"
specifies the variable name ownerId. When the
controller handles this request, the value of
ownerId is set to the value in the request URI.
For example, when a request comes in for /owners/fred, the value fred
is bound to the method parameter String
ownerId.

The matching of method parameter names to URI Template variable
names can only be done if your code is compiled with debugging
enabled. If you do not have debugging enabled, you must specify the
name of the URI Template variable name in the @PathVariable annotation
in order to bind the resolved value of the variable name to a method
parameter. For example:

Method parameters that are decorated with the
@PathVariable annotation can be of
any simple type such as int, long,
Date, etc. Spring automatically converts to the appropriate type and
throws a TypeMismatchException if the type is
not correct. You can further customize this conversion process by
customizing the data binder. See Section 15.3.2.12, “Customizing WebDataBinder
initialization”.

15.3.2.2 Advanced @RequestMapping
options

In addition to URI templates, the
@RequestMapping annotation also
supports Ant-style path patterns (for example,
/myPath/*.do). A combination of URI templates and
Ant-style globs is also supported (for example,
/owners/*/pets/{petId}).

The handler method names are taken into account for narrowing if
no path was specified explicitly, according to the specified
org.springframework.web.servlet.mvc.multiaction.MethodNameResolver
(by default an
org.springframework.web.servlet.mvc.multiaction.InternalPathMethodNameResolver).
This only applies if annotation mappings do not specify a path mapping
explicitly. In other words, the method name is only used for narrowing
among a set of matching methods; it does not constitute a primary path
mapping itself.

If you have a single default method (without explicit path
mapping), then all requests without a more specific mapped method
found are dispatched to it. If you have multiple such default methods,
then the method name is taken into account for choosing between
them.

You can narrow path mappings through parameter conditions: a
sequence of "myParam=myValue" style expressions, with a request only
mapped if each such parameter is found to have the given value. For
example:

"myParam" style expressions are also supported, with such
parameters having to be present in the request (allowed to have any
value). Finally,
"!myParam" style expressions indicate that the specified parameter is
not supposed to be present in the request.

Similarly, path mappings can be narrowed down through header
conditions:

Session object (Servlet API): of type
HttpSession. An argument of this
type enforces the presence of a corresponding session. As a
consequence, such an argument is never
null.

Note

Session access may not be thread-safe, in particular in
a Servlet environment. Consider setting the
AnnotationMethodHandlerAdapter's
"synchronizeOnSession" flag to "true" if multiple requests are
allowed to access a session concurrently.

org.springframework.web.context.request.WebRequest
or
org.springframework.web.context.request.NativeWebRequest.
Allows for generic request parameter access as well as
request/session attribute access, without ties to the native
Servlet/Portlet API.

java.util.Locale for the current
request locale, determined by the most specific locale resolver
available, in effect, the configured
LocaleResolver in a Servlet
environment.

java.io.InputStream /
java.io.Reader for access to the
request's content. This value is the raw InputStream/Reader as
exposed by the Servlet API.

java.io.OutputStream /
java.io.Writer for generating the
response's content. This value is the raw OutputStream/Writer as
exposed by the Servlet API.

HttpEntity<?> parameters
for access to the Servlet request HTTP headers and contents. The request stream will be
converted to the entity body using
HttpMessageConverters. See Section 15.3.2.7, “Using HttpEntity<?>”.

java.util.Map /
org.springframework.ui.Model /
org.springframework.ui.ModelMap for
enriching the implicit model that is exposed to the web
view.

Command or form objects to bind parameters to: as bean
properties or fields, with
customizable type conversion, depending on
@InitBinder methods and/or the
HandlerAdapter configuration. See the
webBindingInitializer property on
AnnotationMethodHandlerAdapter. Such
command objects along with their validation results will be
exposed as model attributes by default, using the non-qualified
command class name in property notation. For
example, "orderAddress" for type "mypackage.OrderAddress".
Specify a parameter-level ModelAttribute
annotation for declaring a specific model attribute name.

org.springframework.web.bind.support.SessionStatus
status handle for marking form processing as complete, which
triggers the cleanup of session attributes that have been
indicated by the @SessionAttributes
annotation at the handler type level.

The Errors or
BindingResult parameters have to follow
the model object that is being bound immediately as the method
signature might have more that one model object and Spring will create
a separate BindingResult instance for
each of them so the following sample won't work:

A ModelAndView object, with the
model implicitly enriched with command objects and the results
of @ModelAttribute annotated reference data
accessor methods.

A Model object, with the
view name implicitly determined through a
RequestToViewNameTranslator and
the model implicitly enriched with command objects and the
results of @ModelAttribute annotated
reference data accessor methods.

A Map object for exposing a
model, with the view name implicitly determined through a
RequestToViewNameTranslator and
the model implicitly enriched with command objects and the
results of @ModelAttribute annotated
reference data accessor methods.

A View object, with the
model implicitly determined through command objects and
@ModelAttribute annotated reference data
accessor methods. The handler method may also programmatically
enrich the model by declaring a
Model argument (see above).

A String value that is interpreted
as the logical view name, with the model implicitly determined
through command objects and @ModelAttribute
annotated reference data accessor methods. The handler method
may also programmatically enrich the model by declaring a
Model argument (see
above).

void if the method handles the response
itself (by writing the response content directly, declaring an
argument of type ServletResponse
/ HttpServletResponse for that
purpose) or if the view name is supposed to be implicitly
determined through a
RequestToViewNameTranslator (not
declaring a response argument in the handler method
signature).

A HttpEntity<?> or
ResponseEntity<?> object
to provide access to the Servlet reponse HTTP headers and
contents. The entity body will be converted to the response
stream using
HttpMessageConverters. See Section 15.3.2.7, “Using HttpEntity<?>”.

Any other return type is considered to be a single model
attribute to be exposed to the view, using the attribute name
specified through @ModelAttribute at the
method level (or the default attribute name based on the return
type class name). The model is implicitly enriched with command
objects and the results of @ModelAttribute
annotated reference data accessor methods.

Parameters using this annotation are required by default, but
you can specify that a parameter is optional by setting
@RequestParam's
required attribute to false
(e.g., @RequestParam(value="id",
required=false)).

15.3.2.5 Mapping the request body with the @RequestBody
annotation

The @RequestBody method parameter
annotation indicates that a method parameter should be bound to the
value of the HTTP request body. For example:

You convert the request body to the method argument by using an
HttpMessageConverter.
HttpMessageConverter is responsible for
converting from the HTTP request message to an object and converting
from an object to the HTTP response body.
DispatcherServlet supports annotation based
processing using the
DefaultAnnotationHandlerMapping and
AnnotationMethodHandlerAdapter. In Spring 3.0
the AnnotationMethodHandlerAdapter is extended
to support the @RequestBody and has the
following HttpMessageConverters
registered by default:

The MarshallingHttpMessageConverter
requires a Marshaller and
Unmarshaller from the
org.springframework.oxm package to be
configured on an instance of
AnnotationMethodHandlerAdapter in the
application context. For example:

15.3.2.6 Mapping the response body with the @ResponseBody
annotation

The @ResponseBody annotation is
similar to @RequestBody. This
annotation can be put on a method and
indicates that the return type should be written straight to the HTTP
response body (and not placed in a Model, or interpreted as a view
name). For example:

The above example will result in the text Hello
World being written to the HTTP response stream.

As with @RequestBody, Spring
converts the returned object to a response body by using an
HttpMessageConverter. For more
information on these converters, see the previous section and Message Converters.

15.3.2.7 Using HttpEntity<?>

The HttpEntity is similar to
@RequestBody and
@ResponseBody. Besides getting
access to the request and response body, HttpEntity
(and the response-specific subclass ResponseEntity)
also allows access to the request and response headers, like so:

The above example gets the value of the "MyRequestHeader" request
header, and reads the body as a byte array. It adds the "MyResponseHeader"
to the response, writes Hello World to the response
stream, and sets the response status code to 201 (Created).

As with @RequestBody and
@ResponseBody, Spring
uses HttpMessageConverter to convert
from and to the request and response streams. For more
information on these converters, see the previous section and Message Converters.

15.3.2.8 Providing a link to data from the model with
@ModelAttribute

@ModelAttribute has two usage scenarios
in controllers. When you place it on a
method parameter, @ModelAttribute maps a model
attribute to the specific, annotated method parameter (see the
processSubmit() method below). This is how the
controller gets a reference to the object holding the data entered in
the form.

You can also use @ModelAttribute at the
method level to provide reference data for the
model (see the populatePetTypes() method in the
following example). For this usage the method signature can contain
the same types as documented previously for the
@RequestMapping annotation.

Note

@ModelAttribute annotated methods are
executed before the chosen
@RequestMapping annotated handler method.
They effectively pre-populate the implicit model with specific
attributes, often loaded from a database. Such an attribute can then
already be accessed through @ModelAttribute
annotated handler method parameters in the chosen handler method,
potentially with binding and validation applied to it.

15.3.2.9 Specifying attributes to store in a session with
@SessionAttributes

The type-level @SessionAttributes
annotation declares session attributes used by a specific handler.
This will typically list the names of model attributes or types of
model attributes which should be transparently stored in the session
or some conversational storage, serving as form-backing beans between
subsequent requests.

The following code snippet shows the usage of this annotation,
specifying the model attribute name:

When using controller interfaces (e.g. for AOP proxying), make sure to
consistently put all your mapping annotations - such as
@RequestMapping and
@SessionAttributes - on the controller
interface rather than on the implementation class.

15.3.2.10 Mapping cookie values with the @CookieValue annotation

The @CookieValue annotation
allows a method parameter to be bound to the value of an HTTP
cookie.

Let us consider that the following cookie has been received with
an http request:

JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84

The following code sample demonstrates how to get the value of
the JSESSIONID cookie:

This annotation is supported for annotated handler methods in
Servlet and Portlet environments.

15.3.2.12 Customizing WebDataBinder
initialization

To customize request parameter binding with PropertyEditors
through Spring's WebDataBinder, you can use
either @InitBinder-annotated methods
within your controller or externalize your configuration by providing
a custom WebBindingInitializer.

Customizing data binding with
@InitBinder

Annotating controller methods with
@InitBinder allows you to configure
web data binding directly within your controller class.
@InitBinder identifies methods that
initialize the WebDataBinder that will be
used to populate command and form object arguments of annotated
handler methods.

Such init-binder methods support all arguments that
@RequestMapping supports, except for
command/form objects and corresponding validation result objects.
Init-binder methods must not have a return value. Thus, they are
usually declared as void. Typical arguments
include WebDataBinder in combination with
WebRequest or
java.util.Locale, allowing code to register
context-specific editors.

The following example demonstrates the use of
@InitBinder to configure a
CustomDateEditor for all
java.util.Date form properties.

Configuring a custom
WebBindingInitializer

To externalize data binding initialization, you can provide a
custom implementation of the
WebBindingInitializer interface,
which you then enable by supplying a custom bean configuration for
an AnnotationMethodHandlerAdapter, thus
overriding the default configuration.

The following example from the PetClinic application shows a
configuration using a custom implementation of the
WebBindingInitializer interface,
org.springframework.samples.petclinic.web.ClinicBindingInitializer,
which configures PropertyEditors required by several of the
PetClinic controllers.

15.4 Handler mappings

In previous versions of Spring, users were required to define
HandlerMappings in the web application
context to map incoming web requests to appropriate handlers. With the
introduction of Spring 2.5, the
DispatcherServlet enables the
DefaultAnnotationHandlerMapping, which looks for
@RequestMapping annotations on
@Controllers. Typically, you do not need to
override this default mapping, unless you need to override the default
property values. These properties are:

Default handler to use, when this handler mapping does not
result in a matching handler.

order

Based on the value of the order property (see the
org.springframework.core.Ordered interface),
Spring sorts all handler mappings available in the context and
applies the first matching handler.

alwaysUseFullPath

If true , Spring uses the full path within
the current servlet context to find an appropriate handler. If
false (the default), the path within the current
servlet mapping is used. For example, if a servlet is mapped using
/testing/* and the
alwaysUseFullPath property is set to true,
/testing/viewPage.html is used, whereas if the
property is set to false, /viewPage.html is
used.

urlDecode

Defaults to true, as of Spring 2.5.
If you prefer to compare encoded paths, set this flag to
false. However, the
HttpServletRequest always exposes the
servlet path in decoded form. Be aware that the servlet path will
not match when compared with encoded paths.

15.4.1 Intercepting requests - the
HandlerInterceptor interface

Spring's handler mapping mechanism includes handler interceptors,
which are useful when you want to apply specific functionality to
certain requests, for example, checking for a principal.

Interceptors located in the handler mapping must implement
HandlerInterceptor from the
org.springframework.web.servlet package. This
interface defines three methods: one is called
before the actual handler is executed; one is
called after the handler is executed; and one is
called after the complete request has finished.
These
three methods should provide enough flexibility to do all kinds of
preprocessing and postprocessing.

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 will continue; 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.

The following example defines a handler mapping which maps all
requests matching the URL patterns "/*.form" and "/*.view" to a
particular controller, editAccountFormController. An
interceptor has been added that intercepts these requests and reroutes
the user to a specific page if the time is not between 9 a.m. and 6
p.m.

Any request handled by this mapping is intercepted by the
TimeBasedAccessInterceptor. If the current time
is outside office hours, the user is redirected to a static HTML file
that says, for example, you can only access the website during office
hours.

As you can see, the Spring adapter class
HandlerInterceptorAdapter makes it easier to
extend the HandlerInterceptor
interface.

15.5 Resolving views

All MVC frameworks for web applications provide a way to address
views. Spring provides view resolvers, which enable you to render models
in a browser without tying you to a specific view technology. Out of the
box, Spring enables you to use JSPs, Velocity templates and XSLT views,
for example. See Chapter 16, View technologies for a discussion of how to
integrate and use a number of disparate view technologies.

The two interfaces that are important to the way Spring handles
views are ViewResolver and
View. The
ViewResolver provides a mapping between
view names and actual views. The View
interface addresses the preparation of the request and hands the request
over to one of the view technologies.

15.5.1 Resolving views with the
ViewResolver interface

As discussed in Section 15.3, “Implementing Controllers”, all handler
methods in the Spring Web MVC controllers must resolve to a logical view
name, either explicitly (e.g., by returning a String,
View, or ModelAndView) or
implicitly (i.e., based on conventions). Views in Spring are addressed
by a logical view name and are resolved by a view resolver. Spring comes
with quite a few view resolvers. This table lists most of them; a couple
of examples follow.

Table 15.3. View resolvers

ViewResolver

Description

AbstractCachingViewResolver

Abstract view resolver that caches views. Often views
need preparation before they can be used; extending this view
resolver provides caching.

XmlViewResolver

Implementation of
ViewResolver that accepts a
configuration file written in XML with the same DTD as Spring's
XML bean factories. The default configuration file is
/WEB-INF/views.xml.

ResourceBundleViewResolver

Implementation of
ViewResolver that uses bean
definitions in a ResourceBundle,
specified by the bundle base name. Typically you define the
bundle in a properties file, located in the classpath. The
default file name is
views.properties.

UrlBasedViewResolver

Simple implementation of the
ViewResolver interface that
effects the direct resolution of logical view names to URLs,
without an explicit mapping definition. This is appropriate if
your logical names match the names of your view resources in a
straightforward manner, without the need for arbitrary
mappings.

InternalResourceViewResolver

Convenient subclass of
UrlBasedViewResolver that supports
InternalResourceView (in effect, Servlets
and JSPs) and subclasses such as JstlView
and TilesView. You can specify the view
class for all views generated by this resolver by using
setViewClass(..). See the Javadocs for the
UrlBasedViewResolver class for
details.

As an example, with JSP as a view technology, you can use the
UrlBasedViewResolver. This view resolver
translates a view name to a URL and hands the request over to the
RequestDispatcher to render the view.

The ResourceBundleViewResolver inspects the
ResourceBundle identified by the basename, and
for each view it is supposed to resolve, it uses the value of the
property [viewname].(class) as the view class and the
value of the property [viewname].url as the view url.
Examples can be found in the next chapter which covers view
technologies. As you can see, you can identify a parent view, from which
all views in the properties file “extend”. This way you can
specify a default view class, for example.

Note

Subclasses of AbstractCachingViewResolver
cache view instances that they resolve. Caching improves performance
of certain view technologies. It's possible to turn off the cache by
setting the cache property to
false. Furthermore, if you must refresh a certain
view at runtime (for example when a Velocity template is modified),
you can use the removeFromCache(String viewName, Locale
loc) method.

15.5.2 Chaining ViewResolvers

Spring supports multiple view resolvers. Thus you can chain
resolvers and, for example, override specific views in certain
circumstances. You chain view resolvers by adding more than one resolver
to your application context 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.

In the following example, the chain of view resolvers consists of
two resolvers, an InternalResourceViewResolver,
which is always automatically positioned as the last resolver in the
chain, and an XmlViewResolver for specifying
Excel views. Excel views are not supported by the
InternalResourceViewResolver.

If a specific view resolver does not result in a view, Spring
examines the context for other view resolvers. If additional view
resolvers exist, Spring continues to inspect them until a view is
resolved. If no view resolver returns a view, Spring throws a
ServletException.

The contract of a view resolver specifies that a view resolver
can return null to indicate the view could not be
found. Not all view resolvers do this, however, because in some cases,
the resolver simply cannot detect whether or not the view exists. For
example, the InternalResourceViewResolver uses
the RequestDispatcher internally, and dispatching
is the only way to figure out if a JSP exists, but this action can only
execute once. The same holds for the
VelocityViewResolver and some others. Check the
Javadoc for the view resolver to see whether it reports non-existing
views. Thus, putting an
InternalResourceViewResolver in the chain in a
place other than the last, results in the chain not being fully
inspected, because the
InternalResourceViewResolver will
always return a view!

15.5.3 Redirecting to views

As mentioned previously, a controller typically returns a logical
view name, which a view resolver resolves to a particular view
technology. For view technologies such as JSPs that are processed
through the Servlet or JSP engine, this resolution is usually handled
through the combination of
InternalResourceViewResolver and
InternalResourceView, which issues an internal
forward or include via the Servlet API's
RequestDispatcher.forward(..) method or
RequestDispatcher.include() method. For other view
technologies, such as Velocity, XSLT, and so on, the view itself writes
the content directly to the response stream.

It is sometimes desirable to issue an HTTP redirect back to the
client, before the view is rendered. This is desirable, for example,
when one controller has been called with POSTed data,
and the response is actually a delegation to another controller (for
example on a successful form submission). In this case, a normal
internal forward will mean that the other controller will also see the
same POST data, which is potentially problematic if
it can confuse it with other expected data. Another reason to perform a
redirect before displaying the result is to eliminate the possibility of
the user submitting the form data multiple times. In this scenario, the
browser will first send an initial POST; it will then
receive a response to redirect to a different URL; and finally the
browser will perform a subsequent GET for the URL
named in the redirect response. Thus, from the perspective of the
browser, the current page does not reflect the result of a
POST but rather of a GET. The end
effect is that there is no way the user can accidentally
re-POST the same data by performing a refresh. The
refresh forces a GET of the result page, not a resend
of the initial POST data.

15.5.3.1 RedirectView

One way to force a redirect as the result of a controller
response is for the controller to create and return an instance of
Spring's RedirectView. In this case,
DispatcherServlet does not use the normal view
resolution mechanism. Rather because it has been given the (redirect)
view already, the DispatcherServlet simply
instructs the view to do its work.

The RedirectView issues an
HttpServletResponse.sendRedirect() call that
returns to the client browser as an HTTP redirect. All
model attributes are exposed as HTTP query parameters. This means that
the model must contain only objects (generally Strings or objects
converted to a String representation), which can be readily converted
to a textual HTTP query parameter.

If you use RedirectView and the view is
created by the controller itself, it is recommended that you configure
the redirect URL to be injected into the controller so that it is not
baked into the controller but configured in the context along with the
view names. The
next section discusses this process.

15.5.3.2 The redirect: prefix

While the use of RedirectView works fine,
if the controller itself creates the
RedirectView, there is no avoiding the fact
that the controller is aware that a redirection is happening. This is
really suboptimal and couples things too tightly. The controller
should not really care about how the response gets handled. In general
it should operate only in terms of view names that have been injected
into it.

The special redirect: prefix allows you to
accomplish this. If a view name is returned that has the prefix
redirect:, the
UrlBasedViewResolver (and all subclasses) will
recognize this as a special indication that a redirect is needed. The
rest of the view name will be treated as the redirect URL.

The net effect is the same as if the controller had returned a
RedirectView, but now the controller itself can
simply operate in terms of logical view names. A logical view name
such as redirect:/my/response/controller.html will
redirect relative to the current servlet context, while a name such as
redirect:http://myhost.com/some/arbitrary/path.html
will redirect to an absolute URL. The important thing is that, as long
as this redirect view name is injected into the controller like any
other logical view name, the controller is not even aware that
redirection is happening.

15.5.3.3 The forward: prefix

It is also possible to use a special forward:
prefix for view names that are ultimately resolved by
UrlBasedViewResolver and subclasses. This
creates an InternalResourceView (which
ultimately does a RequestDispatcher.forward())
around the rest of the view name, which is considered a URL.
Therefore, this prefix is not useful with
InternalResourceViewResolver and
InternalResourceView (for JSPs for example).
But the prefix can be helpful when you are primarily using 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.)

As with the redirect: prefix, if the view
name with the forward: prefix is injected into the
controller, the controller does not detect that anything special is
happening in terms of handling the response.

15.5.4 ContentNegotiatingViewResolver

The ContentNegotiatingViewResolver does not
resolve views itself but rather delegates to other view resolvers,
selecting the view that resembles the representation requested by the
client. Two strategies exist for a client to request a representation
from the server:

Use a distinct URI for each resource, typically by using a
different file extension in the URI. For example, the URI
http://www.example.com/users/fred.pdf requests a PDF
representation of the user fred, and
http://www.example.com/users/fred.xml requests an
XML representation.

Use the same URI for the client to locate the resource, but
set the Accept HTTP request header to list the
media
types that it understands. For example, an HTTP request for
http://www.example.com/users/fred with an
Accept header set to application/pdf
requests a PDF representation of the user fred, while
http://www.example.com/users/fred with an
Accept header set to text/xml
requests an XML representation. This strategy is known as content
negotiation.

Note

One issue with the Accept header is that it
is impossible to set it in a web browser within HTML. For example, in
Firefox, it is fixed to:

For this reason it is common to see the use of a distinct URI
for each representation when developing browser based web
applications.

To support multiple representations of a resource, Spring provides
the ContentNegotiatingViewResolver to resolve a
view based on the file extension or Accept header of
the HTTP request. ContentNegotiatingViewResolver
does not perform the view resolution itself but instead delegates to a
list of view resolvers that you specify through the bean property
ViewResolvers.

The ContentNegotiatingViewResolver selects
an appropriate View to handle the request by
comparing the request media type(s) 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, then the list of views
specified through the DefaultViews property will be
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 may include wildcards, for
example text/*, in which case a View whose
Content-Type was text/xml is a compatible match.

To support the resolution of a view based on a file extension, use
the ContentNegotiatingViewResolver bean property
mediaTypes to specify a mapping of file extensions to
media types. For more information on the algorithm used to determine the
request media type, refer to the API documentation for
ContentNegotiatingViewResolver.

The InternalResourceViewResolver handles
the translation of view names and JSP pages, while the
BeanNameViewResolver returns a view based on the
name of a bean. (See "Resolving views with the
ViewResolver interface" for more details on how Spring looks up
and instantiates a view.) In this example, the
content bean is a class that inherits from
AbstractAtomFeedView, which returns an Atom RSS
feed. For more information on creating an Atom Feed representation, see
the section Atom Views.

In the above configuration, if a request is made with an
.html extension, the view resolver looks for a view
that matches the text/html media type. The
InternalResourceViewResolver provides the
matching view for text/html. If the request is made
with the file extension .atom, the view resolver
looks for a view that matches the
application/atom+xml media type. This view is
provided by the BeanNameViewResolver that maps to
the SampleContentAtomView if the view name
returned is content. If the request is made with
the file extension .json, the
MappingJacksonJsonView instance from the
DefaultViews list will be selected regardless of the
view name. Alternatively, client requests can be made without a file
extension but with the Accept header set to the
preferred media-type, and the same resolution of request to views would
occur.

Note

If ContentNegotiatingViewResolver's list
of ViewResolvers is not configured explicitly, it automatically uses
any ViewResolvers defined in the application context.

The corresponding controller code that returns an Atom RSS feed
for a URI of the form http://localhost/content.atom
or http://localhost/content with an
Accept header of application/atom+xml is shown
below.

15.6 Using locales

Most parts of Spring's architecture support internationalization,
just as the Spring web MVC framework does.
DispatcherServlet enables you to automatically
resolve messages 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. Using the
RequestContext.getLocale() method, you can always
retrieve the locale that was resolved by the locale resolver.

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. Here is a
selection of the locale resolvers included in Spring.

15.6.1 AcceptHeaderLocaleResolver

This locale resolver inspects the
accept-language header in the request that was sent
by the client (e.g., a web browser). Usually this header field contains
the locale of the client's operating system.

15.6.2 CookieLocaleResolver

This locale resolver inspects a Cookie that
might exist on the client to see if a locale is specified. If so, it
uses the specified locale. Using the properties of this locale resolver,
you can specify the name of the cookie as well as the maximum age. Find
below an example of defining a
CookieLocaleResolver.

<beanid="localeResolver"class="org.springframework.web.servlet.i18n.CookieLocaleResolver">
<propertyname="cookieName"value="clientlanguage"/>
<!-- in seconds. If set to -1, the cookie is not persisted (deleted when browser shuts down) -->
<propertyname="cookieMaxAge"value="100000">
</bean>

Table 15.4. CookieLocaleResolver properties

Property

Default

Description

cookieName

classname + LOCALE

The name of the cookie

cookieMaxAge

Integer.MAX_INT

The maximum time a cookie will stay persistent on the
client. If -1 is specified, the cookie will not be persisted; it
will only be available until the client shuts down his or her
browser.

cookiePath

/

Limits the visibility of the cookie to a certain part of
your site. When cookiePath is specified, the cookie will only be
visible to that path and the paths below it.

15.6.3 SessionLocaleResolver

The SessionLocaleResolver allows you to
retrieve locales from the session that might be associated with the
user's request.

15.6.4 LocaleChangeInterceptor

You can enable changing of locales by adding the
LocaleChangeInterceptor to one of the handler
mappings (see Section 15.4, “Handler mappings”). It will detect a
parameter in the request and change the locale. It calls
setLocale() on the
LocaleResolver that also exists in the
context. The following example shows that calls to all
*.view resources containing a parameter named
siteLanguage will now change the locale. So, for
example, a request for the following URL,
http://www.sf.net/home.view?siteLanguage=nl will
change the site language to Dutch.

15.7 Using themes

15.7.1 Overview of 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.

15.7.2 Defining themes

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 will be 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 using the ResourceBundleThemeSource, a
theme is defined in a simple properties file. The
properties file lists the resources that make up the theme. Here is an
example:

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:

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.

15.7.3 Theme resolvers

After you define themes, as in the preceding section, you decide
which theme to use. The DispatcherServlet will
look 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 theme resolvers are provided by Spring:

Table 15.5. ThemeResolver
implementations

Class

Description

FixedThemeResolver

Selects a fixed theme, set using the
defaultThemeName property.

SessionThemeResolver

The theme is maintained in the user's HTTP session. It
only needs to be set once for each session, but is not persisted
between sessions.

CookieThemeResolver

The selected theme is stored in a cookie on the
client.

Spring also provides a
ThemeChangeInterceptor that allows theme changes
on every request with a simple request parameter.

15.8 Spring's multipart (fileupload) support

15.8.1 Introduction

Spring's built-in multipart support handles file uploads in web
applications. You enable this multipart support with pluggable
MultipartResolver objects, defined in the
org.springframework.web.multipart package. Spring
provides a MultipartResolver for use with
Commons FileUpload).

By default, Spring does no multipart handling, because some
developers want to handle multiparts themselves. You enable Spring
multipart handling by adding a multipart resolver to the web
application's context. Each request is inspected to see if it contains a
multipart. If no multipart is found, the request continues as expected.
If a multipart is found in the request, the
MultipartResolver that has been declared in your
context is used. After that, the multipart attribute in your request is
treated like any other attribute.

15.8.2 Using the
MultipartResolver

The following example shows how to use the
CommonsMultipartResolver:

<beanid="multipartResolver"class="org.springframework.web.multipart.commons.CommonsMultipartResolver">
<!-- one of the properties available; the maximum file size in bytes -->
<propertyname="maxUploadSize"value="100000"/>
</bean>

Of course you also need to put the appropriate jars in your
classpath for the multipart resolver to work. In the case of the
CommonsMultipartResolver, you need to use
commons-fileupload.jar.

When the Spring DispatcherServlet detects a
multi-part request, it activates the resolver that has been declared in
your context and hands over the request. The resolver then wraps the
current HttpServletRequest into a
MultipartHttpServletRequest that supports
multipart file uploads. Using the
MultipartHttpServletRequest, you can get
information about the multiparts contained by this request and actually
get access to the multipart files themselves in your controllers.

15.8.3 Handling a file upload in a form

After the MultipartResolver completes its
job, the request is processed like any other. First, create a form with
a file input that will allow the user to upload a form. The encoding
attribute (enctype="multipart/form-data") lets the
browser know how to encode the form as multipart request:

The next step is to create a controller that handles the file
upload. This controller is very similar to a normal annotated
@Controller, except that we use
MultipartHttpServletRequest or
MultipartFile in the method parameters:

Note how the @RequestParam method
parameters map to the input elements declared in the form. In this
example, nothing is done with the byte[], but in
practice you can save it in a database, store it on the file system, and
so on.

Finally, you will have to declare the controller and the resolver
in the application context:

15.9 Handling exceptions

15.9.1 HandlerExceptionResolver

Spring HandlerExceptionResolvers ease the pain
of unexpected exceptions that occur while your request is handled by a
controller that matched the request.
HandlerExceptionResolvers somewhat resemble the
exception mappings you can define in the web application descriptor
web.xml. However, they provide a more flexible way to
handle exceptions. They provide information about which handler was
executing when the exception was thrown. Furthermore, a programmatic way
of handling exceptions gives you more options for responding
appropriately before the request is forwarded to another URL (the same
end result as when you use the servlet specific exception
mappings).

Besides implementing the
HandlerExceptionResolver interface, which
is only a matter of implementing the
resolveException(Exception, Handler) method and
returning a ModelAndView, you may also use the
SimpleMappingExceptionResolver. This resolver
enables you to take the class name of any exception that might be thrown
and map it to a view name. This is functionally equivalent to the
exception mapping feature from the Servlet API, but it is also possible
to implement more finely grained mappings of exceptions from different
handlers.

15.9.2 @ExceptionHandler

An alternative to the
HandlerExceptionResolver interface is the
@ExceptionHandler annotation. You use the
@ExceptionHandler method annotation within a
controller to specify which method is invoked when an exception of a
specific type is thrown during the execution of controller methods. For
example:

will invoke the 'handlerIOException' method when a
java.io.IOException is thrown.

The @ExceptionHandler value can be set to
an array of Exception types. If an exception is thrown matches one of
the types in the list, then the method annotated with the matching
@ExceptionHandler will be invoked. If the
annotation value is not set then the exception types listed as method
arguments are used.

Much like standard controller methods annotated with a
@RequestMapping annotation, the method arguments
and return values of @ExceptionHandler methods
are very flexible. For example, the
HttpServletRequest can be accessed in Servlet
environments and the PortletRequest in Portlet
environments. The return type can be a String,
which is interpreted as a view name or a
ModelAndView object. Refer to the API
documentation for more details.

15.10 Convention over configuration support

For a lot of projects, sticking to established conventions and
having reasonable defaults is just what they (the projects) need... this
theme of convention-over-configuration now has explicit support in Spring
Web MVC. What this means is that if you establish a set of naming
conventions and suchlike, you can substantially cut
down on the amount of configuration that is required to set up handler
mappings, view resolvers, ModelAndView instances,
etc. This is a great boon with regards to rapid prototyping, and can also
lend a degree of (always good-to-have) consistency across a codebase
should you choose to move forward with it into production.

Convention-over-configuration support addresses the three core areas
of MVC -- models, views, and controllers.

15.10.1 The Controller
ControllerClassNameHandlerMapping

The ControllerClassNameHandlerMapping class
is a HandlerMapping implementation that
uses a convention to determine the mapping between request URLs and the
Controller instances that are to handle
those requests.

Consider the following simple
Controller implementation. Take special
notice of the name of the class.

The ControllerClassNameHandlerMapping finds
all of the various handler (or
Controller) beans defined in its
application context and strips Controller off the
name to define its handler mappings. Thus,
ViewShoppingCartController maps to the
/viewshoppingcart* request URL.

Let's look at some more examples so that the central idea becomes
immediately familiar. (Notice all lowercase in the URLs, in contrast to
camel-cased Controller class
names.)

WelcomeController maps to the
/welcome* request URL

HomeController maps to the
/home* request URL

IndexController maps to the
/index* request URL

RegisterController maps to the
/register* request URL

In the case of MultiActionController
handler classes, the mappings generated are slightly more complex. The
Controller names in the following
examples are assumed to be MultiActionController
implementations:

AdminController maps to the
/admin/* request
URL

CatalogController maps to the
/catalog/*
request URL

If you follow the convention of naming your
Controller implementations as
xxxController, the
ControllerClassNameHandlerMapping saves you the
tedium of defining and maintaining a potentially
looooongSimpleUrlHandlerMapping (or suchlike).

The ControllerClassNameHandlerMapping class
extends the AbstractHandlerMapping base class so
you can define HandlerInterceptor
instances and everything else just as you would with many other
HandlerMapping implementations.

15.10.2 The Model ModelMap
(ModelAndView)

The ModelMap class is essentially a
glorified Map that can make adding
objects that are to be displayed in (or on) a
View adhere to a common naming
convention. Consider the following
Controller implementation; notice that
objects are added to the ModelAndView without any
associated name specified.

The ModelAndView class uses a
ModelMap class that is a custom
Map implementation that automatically
generates a key for an object when an object is added to it. The
strategy for determining the name for an added object is, in the case of
a scalar object such as User, to use the short
class name of the object's class. The following examples are names that
are generated for scalar objects put into a
ModelMap instance.

An x.y.User instance added will have
the name user generated.

An x.y.Registration instance added will
have the name registration generated.

An x.y.Foo instance added will have the
name foo generated.

A java.util.HashMap instance added will
have the name hashMap generated. You probably
want to be explicit about the name in this case because
hashMap is less than intuitive.

Adding null will result in an
IllegalArgumentException being thrown. If the
object (or objects) that you are adding could be
null, then you will also want to be explicit
about the name.

What, no automatic pluralisation?

Spring Web MVC's convention-over-configuration support does not
support automatic pluralisation. That is, you cannot add a
List of Person
objects to a ModelAndView and have the
generated name be people.

This decision was made after some debate, with the
“Principle of Least Surprise” winning out in the
end.

The strategy for generating a name after adding a
Set, List
or array object is to peek into the collection, take the short class
name of the first object in the collection, and use that with
List appended to the name. Some examples will make
the semantics of name generation for collections clearer...

An x.y.User[] array with one or more
x.y.User elements added will have the name
userList generated.

An x.y.Foo[] array with one or more
x.y.User elements added will have the name
fooList generated.

A java.util.ArrayList with one or more
x.y.User elements added will have the name
userList generated.

A java.util.HashSet with one or more
x.y.Foo elements added will have the name
fooList generated.

An emptyjava.util.ArrayList will not be added at all
(in effect, the addObject(..) call will
essentially be a no-op).

15.10.3 The View -
RequestToViewNameTranslator

The RequestToViewNameTranslator
interface determines a logical View name
when no such logical view name is explicitly supplied. It has just one
implementation, the
DefaultRequestToViewNameTranslator class.

The DefaultRequestToViewNameTranslator maps
request URLs to logical view names, as with this example:

Notice how in the implementation of the
handleRequest(..) method no
View or logical view name is ever set on
the ModelAndView that is returned. The
DefaultRequestToViewNameTranslator is tasked with
generating a logical view name from the URL of the
request. In the case of the above
RegistrationController, which is used in
conjunction with the
ControllerClassNameHandlerMapping, a request URL
of http://localhost/registration.html results in a
logical view name of registration being generated by
the DefaultRequestToViewNameTranslator. This
logical view name is then resolved into the
/WEB-INF/jsp/registration.jsp view by the
InternalResourceViewResolver bean.

Tip

You do not need to define a
DefaultRequestToViewNameTranslator bean
explicitly. If you like the default settings of the
DefaultRequestToViewNameTranslator, you can
rely on the Spring Web MVC DispatcherServlet to
instantiate an instance of this class if one is not explicitly
configured.

Of course, if you need to change the default settings, then you do
need to configure your own
DefaultRequestToViewNameTranslator bean
explicitly. Consult the comprehensive Javadoc for the
DefaultRequestToViewNameTranslator class for
details of the various properties that can be configured.

15.11 ETag support

An ETag
(entity tag) is an HTTP response header returned by an HTTP/1.1 compliant
web server used to determine change in content at a given URL. It can be
considered to be the more sophisticated successor to the
Last-Modified header. When a server returns a
representation with an ETag header, the client can use this header in
subsequent GETs, in an If-None-Match header. If the
content has not changed, the server returns 304: Not
Modified.

Support for ETags is provided by the servlet filter
ShallowEtagHeaderFilter. It is a plain Servlet
Filter, and thus can be used in combination with any web framework. The
ShallowEtagHeaderFilter filter creates so-called
shallow ETags (as opposed to deep ETags, more about that later).The
filter caches the content of the rendered JSP (or other content),
generates an MD5 hash over that, and returns that as an ETag header in the
response. The next time a client sends a request for the same resource, it
uses that hash as the If-None-Match value. The filter
detects this, renders the view again, and compares the two hashes. If they
are equal, a 304 is returned. This filter will not save
processing power, as the view is still rendered. The only thing it saves
is bandwidth, as the rendered response is not sent back over the
wire.

15.12 Configuring Spring MVC

Spring 3 introduces a mvc XML configuration namespace that simplifies the setup of Spring MVC inside your web application.
Instead of registering low-level beans such as AnnotationMethodHandlerAdapter, you can simply use the namespace and its higher-level constructs.
This is generally preferred unless you require finer-grained control of the configuration at the bean level.

The mvc namespace consists of three tags: mvc:annotation-driven, mvc:interceptors, and mvc:view-controller.
Each of these tags is documented below and in the XML schema.

15.12.1 mvc:annotation-driven

This tag registers the DefaultAnnotationHandlerMapping and AnnotationMethodHandlerAdapter beans that are required for Spring MVC to dispatch requests to @Controllers.
The tag configures those two beans with sensible defaults based on what is present in your classpath.
The defaults are:

Support for Spring 3's Type ConversionService in addition to JavaBeans PropertyEditors during Data Binding.
A ConversionService instance produced by the org.springframework.format.support.FormattingConversionServiceFactoryBean is used by default.
This can be overriden by setting the conversion-service attribute.

Support for formatting Number fields using the @NumberFormat annotation

Support for formatting Date, Calendar, Long, and Joda Time fields using the @DateTimeFormat annotation, if Joda Time 1.3 or higher is present on the classpath.

Support for validating @Controller inputs with @Valid, if a JSR-303 Provider is present on the classpath.
The validation system can be explicitly configured by setting the validator attribute.

Support for reading and writing XML, if JAXB is present on the classpath.

Support for reading and writing JSON, if Jackson is present on the classpath.

15.12.2 mvc:interceptors

This tag allows you to register custom HandlerInterceptors or WebRequestInterceptors that should be applied to all HandlerMapping beans.
You can also restrict the URL paths specifc interceptors apply to.

15.12.3 mvc:view-controller

This tag is a shorcut for defining a ParameterizableViewController that immediately forwards to a view when invoked.
Use it in static cases when there is no Java Controller logic to execute before the view generates the response.

An example of view-controller that forwards to a home page is shown below:

<mvc:view-controllerpath="/"view-name="home"/>

15.12.4 mvc:resources

This tag allows static resource requests following a particular URL pattern to be served by a ResourceHttpRequestHandler from
any of a list of Resource locations. This provides a convenient way to serve static resources from locations other than the
web application root, including locations on the classpath. The cache-period property may be used to set far future expiration headers
(1 year is the recommendation of optimization tools such as Page Speed and YSlow) so that they will be more efficiently utilized by the client. The handler
also properly evaluates the Last-Modified header (if present) so that a 304 status code will be returned as appropriate, avoiding
unnecessary overhead for resources that are already cached by the client. For example, to serve resource requests with a URL pattern of
/resources/** from a public-resources directory within the web application root, the tag would be used as follows:

<mvc:resourcesmapping="/resources/**"location="/public-resources/"/>

To serve these resources with a 1-year future expiration to ensure maximum use of the browser cache and a reduction in HTTP requests made by the browser:

The mapping attribute must be an Ant pattern that can be used by SimpleUrlHandlerMapping, and the location
attribute must specify one or more valid resource directory locations. Multiple resource locations may be specified using a comma-seperated list of values.
The locations specified will be checked in the specified order for the presence of the resource for any given request. For example, to enable the serving
of resources from both the web application root and from a known path of /META-INF/public-web-resources/ in any jar on the classpath, the tag
would be specified as:

When serving resources that may change when a new version of the application is deployed, it is recommended that you incorporate a version string into the
mapping pattern used to request the resources, so that you may force clients to request the newly deployed version of your application's resources. Such a
version string can be parameterized and accessed using SpEL so that it may be easily managed in a single place when deploying new versions.

As an example, let's consider an application that uses a performance-optimized custom build (as recommended) of the Dojo JavaScript library in production, and that the build is generally
deployed within the web application at a path of /public-resources/dojo/dojo.js. Since different parts of Dojo may be incorporated into the
custom build for each new version of the application, the client web browsers need to be forced to re-download that custom-built dojo.js resource
any time a new version of the application is deployed. A simple way to achieve this would be to manage the version of the application in a properties file,
such as:

application.version=1.0.0

and then to make the properties file's values accessible to SpEL as a bean using the util:properties tag:

15.12.5 mvc:default-servlet-handler

This tag allows for mapping the DispatcherServlet to "/" (thus overriding the mapping of the container's default Servlet),
while still allowing static resource requests to be handled by the container's default Servlet. It configures a
DefaultServletHttpRequestHandler with a URL mapping (given a lowest precedence order) of "/**". This handler will
forward all requests to the default Servlet. To enable this feature using the default setup, simply include the tag in the form:

<mvc:default-servlet-handler/>

The caveat to overriding the "/" Servlet mapping is that the RequestDispatcher for the default Servlet must be
retrieved by name rather than by path. The DefaultServletHttpRequestHandler will attempt to auto-detect the default
Servlet for the container at startup time, using a list of known names for most of the major Servlet containers (including Tomcat,
Jetty, Glassfish, JBoss, Resin, WebLogic, and WebSphere). If the default Servlet has been custom configured
with a different name, or if a different Servlet container is being used where the default Servlet name is unknown, then the
default Servlet's name must be explicitly provided as in the following example: