Movatterモバイル変換

"Open for extension…​"A key design principle in Spring Web MVC and in Spring in general is the "Open forextension, closed for modification" principle.

Some methods in the core classes of Spring Web MVC are markedfinal. As a developeryou cannot override these methods to supply your own behavior. This has not been donearbitrarily, but specifically with this principle in mind.

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

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

Spring’s web module includes many unique web support features:

Non-Spring MVC implementations are preferable for some projects. Many teams expect toleverage their existing investment in skills and tools, for example with JSF.

If you do not want to use Spring’s Web MVC, but intend to leverage other solutions thatSpring offers, you can integrate the web MVC framework of your choice with Springeasily. Simply start up a Spring root application context through itsContextLoaderListener, and access it through itsServletContext attribute (orSpring’s respective helper method) from within any action object. No "plug-ins"are involved, so no dedicated integration is necessary. From the web layer’s point ofview, you simply use Spring as a library, with the root application context instance asthe entry point.

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

Figure 22.1. The request processing workflow in Spring Web MVC (high level)

Figure 22.2. Typical context hierarchy in Spring Web MVC

Figure 22.3. Single root context in Spring Web MVC

The SpringDispatcherServlet uses special beans to process requests and render theappropriate views. These beans are part of Spring MVC. You can choose which specialbeans to use by simply configuring one or more of them in theWebApplicationContext.However, you don’t need to do that initially since Spring MVC maintains a list ofdefault beans to use if you don’t configure any. More on that in the next section. Firstsee the table below listing the special bean types theDispatcherServlet relies on.

As mentioned in the previous section for each special bean theDispatcherServletmaintains a list of implementations to use by default. This information is kept in thefileDispatcherServlet.properties in the packageorg.springframework.web.servlet.

All special beans have some reasonable defaults of their own. Sooner or later thoughyou’ll need to customize one or more of the properties these beans provide. For exampleit’s quite common to configure anInternalResourceViewResolver settings itsprefixproperty to the parent location of view files.

Regardless of the details, the important concept to understand here is that onceyouconfigure a special bean such as anInternalResourceViewResolver in yourWebApplicationContext, you effectively override the list of default implementationsthat would have been used otherwise for that special bean type. For example if youconfigure anInternalResourceViewResolver, the default list ofViewResolverimplementations is ignored.

InSection 22.16, “Configuring Spring MVC” you’ll learn about other options for configuring Spring MVC includingMVC Java config and the MVC XML namespace both of which provide a simple starting pointand assume little knowledge of how Spring MVC works. Regardless of how you choose toconfigure your application, the concepts explained in this section are fundamentalshould be of help to you.

After you set up aDispatcherServlet, and a request comes in for that specificDispatcherServlet, theDispatcherServlet starts processing the request as follows:

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

The SpringDispatcherServlet also supports the return of thelast-modification-date, as specified by the Servlet API. The process of determiningthe last modification date for a specific request is straightforward: theDispatcherServlet looks up an appropriate handler mapping and tests whether thehandler that is found implements theLastModified interface. If so, the value of thelong getLastModified(request) method of theLastModified interface is returned tothe client.

You can customize individualDispatcherServlet instances by adding Servletinitialization parameters (init-param elements) to the Servlet declaration in theweb.xml file. See the following table for the list of supported parameters.

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

The@Controller annotation acts as a stereotype for the annotated class, indicatingits 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 beandefinition in the dispatcher’s context. However, the@Controller stereotype alsoallows for autodetection, aligned with Spring general support for detecting componentclasses in the classpath and auto-registering bean definitions for them.

To enable autodetection of such annotated controllers, you add component scanning toyour configuration. Use thespring-context schema as shown in the following XMLsnippet:

<?xml version="1.0" encoding="UTF-8"?><beansxmlns="http://www.springframework.org/schema/beans"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:p="http://www.springframework.org/schema/p"xmlns:context="http://www.springframework.org/schema/context"xsi:schemaLocation="        http://www.springframework.org/schema/beans        http://www.springframework.org/schema/beans/spring-beans.xsd        http://www.springframework.org/schema/context        http://www.springframework.org/schema/context/spring-context.xsd"><context:component-scanbase-package="org.springframework.samples.petclinic.web"/><!-- ... --></beans>

You use the@RequestMapping annotation to map URLs such as/appointments onto anentire class or a particular handler method. Typically the class-level annotation maps aspecific request path (or path pattern) onto a form controller, with additionalmethod-level annotations narrowing the primary mapping for a specific HTTP methodrequest method ("GET", "POST", etc.) or an HTTP request parameter condition.

The following example from thePetcare sample shows a controller in a Spring MVCapplication that uses this annotation:

@Controller@RequestMapping("/appointments")publicclass AppointmentsController {privatefinal AppointmentBook appointmentBook;@Autowiredpublic AppointmentsController(AppointmentBook appointmentBook) {this.appointmentBook = appointmentBook;    }@RequestMapping(method = RequestMethod.GET)public Map<String, Appointment> get() {return appointmentBook.getAppointmentsForToday();    }@RequestMapping(path = "/{day}", method = RequestMethod.GET)public Map<String, Appointment> getForDay(@PathVariable@DateTimeFormat(iso=ISO.DATE) Date day, Model model) {return appointmentBook.getAppointmentsForDay(day);    }@RequestMapping(path = "/new", method = RequestMethod.GET)public AppointmentForm getNewForm() {returnnew AppointmentForm();    }@RequestMapping(method = RequestMethod.POST)public String add(@Valid AppointmentForm appointment, BindingResult result) {if (result.hasErrors()) {return"appointments/new";        }        appointmentBook.addAppointment(appointment);return"redirect:/appointments";    }}

In the above example,@RequestMapping is used in a number of places. The first usage ison the type (class) level, which indicates that all handler methods in this controllerare relative to the/appointments path. Theget() method has a further@RequestMapping refinement: it only acceptsGET requests, meaning that an HTTPGET for/appointments invokes this method. Theadd() has a similar refinement, and thegetNewForm() combines the definition of HTTP method and path into one, so thatGETrequests forappointments/new are handled by that method.

ThegetForDay() method shows another usage of@RequestMapping: URI templates. (Seethe section called “URI Template Patterns”).

A@RequestMapping on the class level is not required. Without it, all paths are simplyabsolute, and not relative. The following example from thePetClinic sampleapplication shows a multi-action controller using@RequestMapping:

@Controllerpublicclass ClinicController {privatefinal Clinic clinic;@Autowiredpublic ClinicController(Clinic clinic) {this.clinic = clinic;    }@RequestMapping("/")publicvoid welcomeHandler() {    }@RequestMapping("/vets")public ModelMap vetsHandler() {returnnew ModelMap(this.clinic.getVets());    }}

The above example does not specifyGET vs.PUT,POST, and so forth, because@RequestMapping maps all HTTP methods by default. Use@RequestMapping(method=GET) or@GetMapping to narrow the mapping.

@Controller@RequestMapping("/appointments")publicclass AppointmentsController {privatefinal AppointmentBook appointmentBook;@Autowiredpublic AppointmentsController(AppointmentBook appointmentBook) {this.appointmentBook = appointmentBook;    }@GetMappingpublic Map<String, Appointment> get() {return appointmentBook.getAppointmentsForToday();    }@GetMapping("/{day}")public Map<String, Appointment> getForDay(@PathVariable@DateTimeFormat(iso=ISO.DATE) Date day, Model model) {return appointmentBook.getAppointmentsForDay(day);    }@GetMapping("/new")public AppointmentForm getNewForm() {returnnew AppointmentForm();    }@PostMappingpublic String add(@Valid AppointmentForm appointment, BindingResult result) {if (result.hasErrors()) {return"appointments/new";        }        appointmentBook.addAppointment(appointment);return"redirect:/appointments";    }}

URI Template Patterns

URI templates can be used for convenient access to selected parts of a URL in a@RequestMapping method.

A URI Template is a URI-like string, containing one or more variable names. When yousubstitute values for these variables, the template becomes a URI. Theproposed RFC for URI Templates defineshow a URI is parameterized. For example, the URI Templatehttp://www.example.com/users/{userId} contains the variableuserId. Assigning thevaluefred to the variable yieldshttp://www.example.com/users/fred.

In Spring MVC you can use the@PathVariable annotation on a method argument to bind itto the value of a URI template variable:

@GetMapping("/owners/{ownerId}")public String findOwner(@PathVariable String ownerId, Model model) {    Owner owner = ownerService.findOwner(ownerId);    model.addAttribute("owner", owner);return"displayOwner";}

The URI Template "/owners/{ownerId}`" specifies the variable name `ownerId. When thecontroller handles this request, the value ofownerId is set to the value found in theappropriate part of the URI. For example, when a request comes in for/owners/fred,the value ofownerId isfred.

Tip

To process the @PathVariable annotation, Spring MVC needs to find the matching URItemplate variable by name. You can specify it in the annotation: @GetMapping("/owners/{ownerId}")public String findOwner(@PathVariable("ownerId") String theOwner, Model model) {// implementation omitted} Or if the URI template variable name matches the method argument name you can omit thatdetail. As long as your code is compiled with debugging information or the-parameterscompiler flag on Java 8, Spring MVC will match the method argument name to the URItemplate variable name: @GetMapping("/owners/{ownerId}")public String findOwner(@PathVariable String ownerId, Model model) {// implementation omitted}

A method can have any number of@PathVariable annotations:

@GetMapping("/owners/{ownerId}/pets/{petId}")public String findPet(@PathVariable String ownerId,@PathVariable String petId, Model model) {    Owner owner = ownerService.findOwner(ownerId);    Pet pet = owner.getPet(petId);    model.addAttribute("pet", pet);return"displayPet";}

When a@PathVariable annotation is used on aMap<String, String> argument, the mapis populated with all URI template variables.

A URI template can be assembled from type and method level@RequestMappingannotations. As a result thefindPet() method can be invoked with a URL such as/owners/42/pets/21.

@Controller@RequestMapping("/owners/{ownerId}")publicclass RelativePathUriTemplateController {    @RequestMapping("/pets/{petId}")publicvoid findPet(@PathVariable String ownerId,@PathVariable String petId, Model model) {// implementation omitted    }}

A@PathVariable argument can be ofany simple type such asint,long,Date, etc.Spring automatically converts to the appropriate type or throws aTypeMismatchException if it fails to do so. You can also register support for parsingadditional data types. Seethe section called “Method Parameters And Type Conversion” andthe section called “Customizing WebDataBinder initialization”.

@RequestMapping("/spring-web/{symbolicName:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{extension:\\.[a-z]+}")publicvoid handle(@PathVariable String version,@PathVariable String extension) {// ...}

Suffix Pattern Matching and RFD

Reflected file download (RFD) attack was first described in apaper by Trustwavein 2014. The attack is similar to XSS in that it relies on input(e.g. query parameter, URI variable) being reflected in the response.However instead of inserting JavaScript into HTML, an RFD attack relies on thebrowser switching to perform a download and treating the response as an executablescript if double-clicked based on the file extension (e.g. .bat, .cmd).

In Spring MVC@ResponseBody andResponseEntity methods are at risk becausethey can render different content types which clients can request includingvia URL path extensions. Note however that neither disabling suffix pattern matchingnor disabling the use of path extensions for content negotiation purposes aloneare effective at preventing RFD attacks.

For comprehensive protection against RFD, prior to rendering the response bodySpring MVC adds aContent-Disposition:inline;filename=f.txt header tosuggest a fixed and safe download file filename. This is done only if the URLpath contains a file extension that is neither whitelisted nor explicitlyregistered for content negotiation purposes. However it may potentially haveside effects when URLs are typed directly into a browser.

Many common path extensions are whitelisted bydefault. Furthermore REST API calls are typically not meant to be used as URLsdirectly in browsers. Nevertheless applications that use customHttpMessageConverter implementations can explicitly register file extensionsfor content negotiation and the Content-Disposition header will not be addedfor such extensions. SeeSection 22.16.6, “Content Negotiation”.

Note

This was originally introduced as part of work forCVE-2015-5211.Below are additional recommendations from the report: Encode rather than escape JSON responses. This is also an OWASP XSS recommendation.For an example of how to do that with Spring seespring-jackson-owasp. Configure suffix pattern matching to be turned off or restricted to explicitlyregistered suffixes only. Configure content negotiation with the properties "useJaf" and "ignoreUnknownPathExtensions"set to false which would result in a 406 response for URLs with unknown extensions.Note however that this may not be an option if URLs are naturally expected to havea dot towards the end. AddX-Content-Type-Options: nosniff header to responses. Spring Security 4 doesthis by default.

Matrix Variables

The URI specificationRFC 3986 definesthe possibility of including name-value pairs within path segments. There is no specificterm used in the spec. The general "URI path parameters" could be applied although themore unique"Matrix URIs", originatingfrom an old post by Tim Berners-Lee, is also frequently used and fairly well known.Within Spring MVC these are referred to as matrix variables.

Matrix variables can appear in any path segment, each matrix variable separated with a";" (semicolon). For example:"/cars;color=red;year=2012". Multiple values may beeither "," (comma) separated"color=red,green,blue" or the variable name may berepeated"color=red;color=green;color=blue".

If a URL is expected to contain matrix variables, the request mapping pattern mustrepresent them with a URI template. This ensures the request can be matched correctlyregardless of whether matrix variables are present or not and in what order they areprovided.

Below is an example of extracting the matrix variable "q":

// GET /pets/42;q=11;r=22@GetMapping("/pets/{petId}")publicvoid findPet(@PathVariable String petId,@MatrixVariableint q) {// petId == 42// q == 11}

Since all path segments may contain matrix variables, in some cases you need to be morespecific to identify where the variable is expected to be:

// GET /owners/42;q=11/pets/21;q=22@GetMapping("/owners/{ownerId}/pets/{petId}")publicvoid findPet(@MatrixVariable(name="q", pathVar="ownerId")int q1,@MatrixVariable(name="q", pathVar="petId")int q2) {// q1 == 11// q2 == 22}

A matrix variable may be defined as optional and a default value specified:

// GET /pets/42@GetMapping("/pets/{petId}")publicvoid findPet(@MatrixVariable(required=false, defaultValue="1")int q) {// q == 1}

All matrix variables may be obtained in a Map:

// GET /owners/42;q=11;r=12/pets/21;q=22;s=23@GetMapping("/owners/{ownerId}/pets/{petId}")publicvoid findPet(@MatrixVariable MultiValueMap<String, String> matrixVars,@MatrixVariable(pathVar="petId"") MultiValueMap<String, String> petMatrixVars) {// matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]// petMatrixVars: ["q" : 11, "s" : 23]}

Note that to enable the use of matrix variables, you must set theremoveSemicolonContent property ofRequestMappingHandlerMapping tofalse. Bydefault it is set totrue.

Tip

The MVC Java config and the MVC namespace both provide options for enabling the use ofmatrix variables. If you are using Java config, TheAdvanced Customizationswith MVC Java Config section describes how theRequestMappingHandlerMapping canbe customized. In the MVC namespace, the<mvc:annotation-driven> element has anenable-matrix-variables attribute that should be set totrue. By default it is settofalse. <?xml version="1.0" encoding="UTF-8"?><beansxmlns="http://www.springframework.org/schema/beans"xmlns:mvc="http://www.springframework.org/schema/mvc"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc.xsd"><mvc:annotation-drivenenable-matrix-variables="true"/></beans>

Consumable Media Types

You can narrow the primary mapping by specifying a list of consumable media types. Therequest will be matched only if theContent-Type request header matches the specifiedmedia type. For example:

@PostMapping(path ="/pets",consumes = "application/json")publicvoid addPet(@RequestBody Pet pet, Model model) {// implementation omitted}

Consumable media type expressions can also be negated as in!text/plain to match toall requests other than those withContent-Type oftext/plain. Also considerusing constants provided inMediaType such asAPPLICATION_JSON_VALUE andAPPLICATION_JSON_UTF8_VALUE.

	Tip
	Theconsumes condition is supported on the type and on the method level. Unlike mostother conditions, when used at the type level, method-level consumable types overriderather than extend type-level consumable types.

Producible Media Types

You can narrow the primary mapping by specifying a list of producible media types. Therequest will be matched only if theAccept request header matches one of thesevalues. Furthermore, use of theproduces condition ensures the actual content typeused to generate the response respects the media types specified in theproducescondition. For example:

@GetMapping(path ="/pets/{petId}",produces = MediaType.APPLICATION_JSON_UTF8_VALUE)@ResponseBodypublic Pet getPet(@PathVariable String petId, Model model) {// implementation omitted}

	Note
	Be aware that the media type specified in theproduces condition can also optionallyspecify a character set. For example, in the code snippet above we specify the same mediatype than the default one configured inMappingJackson2HttpMessageConverter, includingtheUTF-8 charset.

Just like withconsumes, producible media type expressions can be negated as in!text/plain to match to all requests other than those with anAccept headervalue oftext/plain. Also consider using constants provided inMediaType suchasAPPLICATION_JSON_VALUE andAPPLICATION_JSON_UTF8_VALUE.

	Tip
	Theproduces condition is supported on the type and on the method level. Unlike mostother conditions, when used at the type level, method-level producible types overriderather than extend type-level producible types.

Request Parameters and Header Values

You can narrow request matching through request parameter conditions such as"myParam","!myParam", or"myParam=myValue". The first two test for requestparameter presence/absence and the third for a specific parameter value. Here is anexample with a request parameter value condition:

@Controller@RequestMapping("/owners/{ownerId}")publicclass RelativePathUriTemplateController {    @GetMapping(path ="/pets/{petId}",params = "myParam=myValue")publicvoid findPet(@PathVariable String ownerId,@PathVariable String petId, Model model) {// implementation omitted    }}

The same can be done to test for request header presence/absence or to match based on aspecific request header value:

@Controller@RequestMapping("/owners/{ownerId}")publicclass RelativePathUriTemplateController {    @GetMapping(path ="/pets",headers = "myHeader=myValue")publicvoid findPet(@PathVariable String ownerId,@PathVariable String petId, Model model) {// implementation omitted    }}

	Tip
	Although you can match toContent-Type andAccept header values using media typewild cards (for example"content-type=text/*" will match to"text/plain" and"text/html"), it is recommended to use theconsumes andproduces conditionsrespectively instead. They are intended specifically for that purpose.

@RequestMapping handler methods can have very flexible signatures. The supportedmethod arguments and return values are described in the following section. Mostarguments can be used in arbitrary order with the only exception beingBindingResultarguments. This is described in the next section.

Note

Spring 3.1 introduced a new set of support classes for@RequestMapping methods calledRequestMappingHandlerMapping andRequestMappingHandlerAdapter respectively. They arerecommended for use and even required to take advantage of new features in Spring MVC3.1 and going forward. The new support classes are enabled by default from the MVCnamespace and with use of the MVC Java config but must be configured explicitly if usingneither.

Supported method argument types

The following are the supported method arguments:

• Request or response objects (Servlet API). Choose any specific request or responsetype, for exampleServletRequest orHttpServletRequest.
• Session object (Servlet API): of typeHttpSession. An argument of this type enforcesthe presence of a corresponding session. As a consequence, such an argument is nevernull.

	Note
	Session access may not be thread-safe, in particular in a Servlet environment. Considersetting theRequestMappingHandlerAdapter's "synchronizeOnSession" flag to "true" ifmultiple requests are allowed to access a session concurrently.

• org.springframework.web.context.request.WebRequest ororg.springframework.web.context.request.NativeWebRequest. Allows for genericrequest parameter access as well as request/session attribute access, without tiesto the native Servlet/Portlet API.
• java.util.Locale for the current request locale, determined by the most specificlocale resolver available, in effect, the configuredLocaleResolver /LocaleContextResolver in an MVC environment.
• java.util.TimeZone (Java 6+) /java.time.ZoneId (on Java 8) for the time zoneassociated with the current request, as determined by aLocaleContextResolver.
• 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.
• org.springframework.http.HttpMethod for the HTTP request method.
• java.security.Principal containing the currently authenticated user.
• @PathVariable annotated parameters for access to URI template variables. Seethe section called “URI Template Patterns”.
• @MatrixVariable annotated parameters for access to name-value pairs located inURI path segments. Seethe section called “Matrix Variables”.
• @RequestParam annotated parameters for access to specific Servlet requestparameters. Parameter values are converted to the declared method argument type.Seethe section called “Binding request parameters to method parameters with @RequestParam”.
• @RequestHeader annotated parameters for access to specific Servlet request HTTPheaders. Parameter values are converted to the declared method argument type.Seethe section called “Mapping request header attributes with the @RequestHeader annotation”.
• @RequestBody annotated parameters for access to the HTTP request body. Parametervalues are converted to the declared method argument type usingHttpMessageConverters. Seethe section called “Mapping the request body with the @RequestBody annotation”.
• @RequestPart annotated parameters for access to the content of a"multipart/form-data" request part. SeeSection 22.10.5, “Handling a file upload request from programmatic clients” andSection 22.10, “Spring’s multipart (file upload) support”.
• @SessionAttribute annotated parameters for access to existing, permanentsession attributes (e.g. user authentication object) as opposed to modelattributes temporarily stored in the session as part of a controller workflowvia@SessionAttributes.
• @RequestAttribute annotated parameters for access to request attributes.
• HttpEntity<?> parameters for access to the Servlet request HTTP headers andcontents. The request stream will be converted to the entity body usingHttpMessageConverters. Seethe section called “Using HttpEntity”.
• java.util.Map /org.springframework.ui.Model /org.springframework.ui.ModelMapfor enriching the implicit model that is exposed to the web view.
• org.springframework.web.servlet.mvc.support.RedirectAttributes to specify the exactset of attributes to use in case of a redirect and also to add flash attributes(attributes stored temporarily on the server-side to make them available to therequest after the redirect). Seethe section called “Passing Data To the Redirect Target” andSection 22.6, “Using flash attributes”.
• Command or form objects to bind request parameters to bean properties (via setters)or directly to fields, with customizable type conversion, depending on@InitBindermethods and/or the HandlerAdapter configuration. See thewebBindingInitializerproperty onRequestMappingHandlerAdapter. Such command objects along with theirvalidation results will be exposed as model attributes by default, using the commandclass name - e.g. model attribute "orderAddress" for a command object of type"some.package.OrderAddress". TheModelAttribute annotation can be used on a methodargument to customize the model attribute name used.
• org.springframework.validation.Errors /org.springframework.validation.BindingResult validation results for a precedingcommand or form object (the immediately preceding method argument).
• org.springframework.web.bind.support.SessionStatus status handle for marking formprocessing as complete, which triggers the cleanup of session attributes that havebeen indicated by the@SessionAttributes annotation at the handler type level.
• org.springframework.web.util.UriComponentsBuilder a builder for preparing a URLrelative to the current request’s host, port, scheme, context path, and the literalpart of the servlet mapping.

TheErrors orBindingResult parameters have to follow the model object that is beingbound immediately as the method signature might have more than one model object andSpring will create a separateBindingResult instance for each of them so the followingsample won’t work:

Invalid ordering of BindingResult and @ModelAttribute. 

@PostMappingpublic String processSubmit(@ModelAttribute("pet") Pet pet, Model model,BindingResult result) { ... }

Note, that there is aModel parameter in betweenPet andBindingResult. To getthis working you have to reorder the parameters as follows:

@PostMappingpublic String processSubmit(@ModelAttribute("pet") Pet pet,BindingResult result, Model model) { ... }

	Note
	JDK 1.8’sjava.util.Optional is supported as a method parameter type with annotationsthat have arequired attribute (e.g.@RequestParam,@RequestHeader, etc. The useofjava.util.Optional in those cases is equivalent to havingrequired=false.

@Controller@RequestMapping("/pets")@SessionAttributes("pet")publicclass EditPetForm {// ...@GetMappingpublic String setupForm(@RequestParam("petId") int petId, ModelMap model) {        Pet pet =this.clinic.loadPet(petId);        model.addAttribute("pet", pet);return"petForm";    }// ...}

Mapping the request body with the @RequestBody annotation

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

@PutMapping("/something")publicvoid handle(@RequestBody String body, Writer writer)throws IOException {    writer.write(body);}

You convert the request body to the method argument by using anHttpMessageConverter.HttpMessageConverter is responsible for converting from the HTTP request message to anobject and converting from an object to the HTTP response body. TheRequestMappingHandlerAdapter supports the@RequestBody annotation with the followingdefaultHttpMessageConverters:

• ByteArrayHttpMessageConverter converts byte arrays.
• StringHttpMessageConverter converts strings.
• FormHttpMessageConverter converts form data to/from a MultiValueMap<String, String>.
• SourceHttpMessageConverter converts to/from a javax.xml.transform.Source.

For more information on these converters, seeMessageConverters. Also note that if using the MVC namespace or the MVC Java config, a widerrange of message converters are registered by default. SeeSection 22.16.1, “Enabling the MVC Java Config or the MVC XML Namespace” for more information.

If you intend to read and write XML, you will need to configure theMarshallingHttpMessageConverter with a specificMarshaller and anUnmarshallerimplementation from theorg.springframework.oxm package. The example below shows howto do that directly in your configuration but if your application is configured throughthe MVC namespace or the MVC Java config seeSection 22.16.1, “Enabling the MVC Java Config or the MVC XML Namespace” instead.

<beanclass="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter"><propertyname="messageConverters"><util:listid="beanList"><refbean="stringHttpMessageConverter"/><refbean="marshallingHttpMessageConverter"/></util:list></property</bean><beanid="stringHttpMessageConverter"class="org.springframework.http.converter.StringHttpMessageConverter"/><beanid="marshallingHttpMessageConverter"class="org.springframework.http.converter.xml.MarshallingHttpMessageConverter"><propertyname="marshaller"ref="castorMarshaller"/><propertyname="unmarshaller"ref="castorMarshaller"/></bean><beanid="castorMarshaller"class="org.springframework.oxm.castor.CastorMarshaller"/>

An@RequestBody method parameter can be annotated with@Valid, in which case it willbe validated using the configuredValidator instance. When using the MVC namespace orthe MVC Java config, a JSR-303 validator is configured automatically assuming a JSR-303implementation is available on the classpath.

Just like with@ModelAttribute parameters, anErrors argument can be used to examinethe errors. If such an argument is not declared, aMethodArgumentNotValidExceptionwill be raised. The exception is handled in theDefaultHandlerExceptionResolver, whichsends a400 error back to the client.

	Note
	Also seeSection 22.16.1, “Enabling the MVC Java Config or the MVC XML Namespace” forinformation on configuring message converters and a validator through the MVC namespaceor the MVC Java config.

@GetMapping("/something")@ResponseBodypublic String helloWorld() {return"Hello World";}

@RequestMapping("/something")public ResponseEntity<String> handle(HttpEntity<byte[]> requestEntity)throws UnsupportedEncodingException {    String requestHeader = requestEntity.getHeaders().getFirst("MyRequestHeader"));byte[] requestBody = requestEntity.getBody();// do something with request header and body    HttpHeaders responseHeaders =new HttpHeaders();    responseHeaders.set("MyResponseHeader","MyValue");returnnew ResponseEntity<String>("Hello World", responseHeaders, HttpStatus.CREATED);}

Using @ModelAttribute on a method

The@ModelAttribute annotation can be used on methods or on method arguments. Thissection explains its usage on methods while the next section explains its usage onmethod arguments.

An@ModelAttribute on a method indicates the purpose of that method is to add one ormore model attributes. Such methods support the same argument types as@RequestMappingmethods but cannot be mapped directly to requests. Instead@ModelAttribute methods ina controller are invoked before@RequestMapping methods, within the same controller. Acouple of examples:

// Add one attribute// The return value of the method is added to the model under the name "account"// You can customize the name via @ModelAttribute("myAccount")@ModelAttributepublic Account addAccount(@RequestParam String number) {return accountManager.findAccount(number);}// Add multiple attributes@ModelAttributepublicvoid populateModel(@RequestParam String number, Model model) {    model.addAttribute(accountManager.findAccount(number));// add more ...}

@ModelAttribute methods are used to populate the model with commonly needed attributesfor example to fill a drop-down with states or with pet types, or to retrieve a commandobject like Account in order to use it to represent the data on an HTML form. The lattercase is further discussed in the next section.

Note the two styles of@ModelAttribute methods. In the first, the method adds anattribute implicitly by returning it. In the second, the method accepts aModel andadds any number of model attributes to it. You can choose between the two stylesdepending on your needs.

A controller can have any number of@ModelAttribute methods. All such methods areinvoked before@RequestMapping methods of the same controller.

@ModelAttribute methods can also be defined in an@ControllerAdvice-annotated classand such methods apply to many controllers. See thethe section called “Advising controllers with @ControllerAdvice and @RestControllerAdvice” sectionfor more details.

Tip

What happens when a model attribute name is not explicitly specified? In such cases adefault name is assigned to the model attribute based on its type. For example if themethod returns an object of typeAccount, the default name used is "account". You canchange that through the value of the@ModelAttribute annotation. If adding attributesdirectly to theModel, use the appropriate overloadedaddAttribute(..) method -i.e., with or without an attribute name.

The@ModelAttribute annotation can be used on@RequestMapping methods as well. Inthat case the return value of the@RequestMapping method is interpreted as a modelattribute rather than as a view name. The view name is then derived based on view nameconventions instead, much like for methods returningvoid — seeSection 22.13.3, “Default view name”.

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")public String processSubmit(@ModelAttribute Pet pet) { }

@PutMapping("/accounts/{account}")public String save(@ModelAttribute("account") Account account) {// ...}

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) {if (result.hasErrors()) {return"petForm";    }// ...}

@ModelAttributepublic AccountForm setUpForm() {returnnew AccountForm();}@ModelAttributepublic Account findAccount(@PathVariable String accountId) {return accountRepository.findOne(accountId);}@PostMapping("update")public String update(@Valid AccountUpdateForm form, BindingResult result,@ModelAttribute(binding=false) Account account) {// ...}

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) {new PetValidator().validate(pet, result);if (result.hasErrors()) {return"petForm";    }// ...}

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) {if (result.hasErrors()) {return"petForm";    }// ...}

@Controller@RequestMapping("/editPet.do")@SessionAttributes("pet")publicclass EditPetForm {// ...}

@RequestMapping("/")public String handle(@SessionAttribute User user) {// ...}

@RequestMapping("/")public String handle(@RequestAttribute Client client) {// ...}

Working with "application/x-www-form-urlencoded" data

The previous sections covered use of@ModelAttribute to support form submissionrequests from browser clients. The same annotation is recommended for use with requestsfrom non-browser clients as well. However there is one notable difference when it comesto working with HTTP PUT requests. Browsers can submit form data via HTTP GET or HTTPPOST. Non-browser clients can also submit forms via HTTP PUT. This presents a challengebecause the Servlet specification requires theServletRequest.getParameter*() familyof methods to support form field access only for HTTP POST, not for HTTP PUT.

To support HTTP PUT and PATCH requests, thespring-web module provides the filterHttpPutFormContentFilter, which can be configured inweb.xml:

<filter><filter-name>httpPutFormFilter</filter-name><filter-class>org.springframework.web.filter.HttpPutFormContentFilter</filter-class></filter><filter-mapping><filter-name>httpPutFormFilter</filter-name><servlet-name>dispatcherServlet</servlet-name></filter-mapping><servlet><servlet-name>dispatcherServlet</servlet-name><servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class></servlet>

The above filter intercepts HTTP PUT and PATCH requests with content typeapplication/x-www-form-urlencoded, reads the form data from the body of the request,and wraps theServletRequest in order to make the form data available through theServletRequest.getParameter*() family of methods.

	Note
	AsHttpPutFormContentFilter consumes the body of the request, it should not beconfigured for PUT or PATCH URLs that rely on other converters forapplication/x-www-form-urlencoded. This includes@RequestBody MultiValueMap<String,String> andHttpEntity<MultiValueMap<String, String>>.

JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84

@RequestMapping("/displayHeaderInfo.do")publicvoid displayHeaderInfo(@CookieValue("JSESSIONID") String cookie) {//...}

Mapping request header attributes with the @RequestHeader annotation

The@RequestHeader annotation allows a method parameter to be bound to a request header.

Here is a sample request header:

Host                    localhost:8080Accept                  text/html,application/xhtml+xml,application/xml;q=0.9Accept-Language         fr,en-gb;q=0.7,en;q=0.3Accept-Encoding         gzip,deflateAccept-Charset          ISO-8859-1,utf-8;q=0.7,*;q=0.7Keep-Alive              300

The following code sample demonstrates how to get the value of theAccept-Encoding andKeep-Alive headers:

@RequestMapping("/displayHeaderInfo.do")publicvoid displayHeaderInfo(@RequestHeader("Accept-Encoding") String encoding,@RequestHeader("Keep-Alive")long keepAlive) {//...}

Type conversion is applied automatically if the method parameter is notString. Seethe section called “Method Parameters And Type Conversion”.

When an@RequestHeader annotation is used on aMap<String, String>,MultiValueMap<String, String>, orHttpHeaders argument, the map is populatedwith all header values.

	Tip
	Built-in support is available for converting a comma-separated string into anarray/collection of strings or other types known to the type conversion system. Forexample a method parameter annotated with@RequestHeader("Accept") may be of typeString but alsoString[] orList<String>.

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

@Controllerpublicclass MyFormController {@InitBinderprotectedvoid initBinder(WebDataBinder binder) {        SimpleDateFormat dateFormat =new SimpleDateFormat("yyyy-MM-dd");        dateFormat.setLenient(false);        binder.registerCustomEditor(Date.class,new CustomDateEditor(dateFormat, false));    }// ...}

@Controllerpublicclass MyFormController {@InitBinderprotectedvoid initBinder(WebDataBinder binder) {        binder.addCustomFormatter(new DateFormatter("yyyy-MM-dd"));    }// ...}

<beanclass="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter"><propertyname="cacheSeconds"value="0"/><propertyname="webBindingInitializer"><beanclass="org.springframework.samples.petclinic.web.ClinicBindingInitializer"/></property></bean>

// Target all Controllers annotated with @RestController@ControllerAdvice(annotations = RestController.class)publicclass AnnotationAdvice {}// Target all Controllers within specific packages@ControllerAdvice("org.example.controllers")publicclass BasePackageAdvice {}// Target all Controllers assignable to specific classes@ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class})publicclass AssignableTypesAdvice {}

Jackson Serialization View Support

It can sometimes be useful to filter contextually the object that will be serialized to theHTTP response body. In order to provide such capability, Spring MVC has built-in support forrendering withJackson’s Serialization Views.

To use it with an@ResponseBody controller method or controller methods that returnResponseEntity, simply add the@JsonView annotation with a class argument specifyingthe view class or interface to be used:

@RestControllerpublicclass UserController {@GetMapping("/user")@JsonView(User.WithoutPasswordView.class)public User getUser() {returnnew User("eric","7!jd#h23");    }}publicclass User {publicinterface WithoutPasswordView {};publicinterface WithPasswordViewextends WithoutPasswordView {};private String username;private String password;public User() {    }public User(String username, String password) {this.username = username;this.password = password;    }@JsonView(WithoutPasswordView.class)public String getUsername() {returnthis.username;    }@JsonView(WithPasswordView.class)public String getPassword() {returnthis.password;    }}

	Note
	Note that despite@JsonView allowing for more than one class tobe specified, the use on a controller method is only supported withexactly one class argument. Consider the use of a composite interfaceif you need to enable multiple views.

For controllers relying on view resolution, simply add the serialization view classto the model:

@Controllerpublicclass UserControllerextends AbstractController {@GetMapping("/user")public String getUser(Model model) {        model.addAttribute("user",new User("eric","7!jd#h23"));        model.addAttribute(JsonView.class.getName(), User.WithoutPasswordView.class);return"userView";    }}

@ControllerAdvicepublicclass JsonpAdviceextends AbstractJsonpResponseBodyAdvice {public JsonpAdvice() {super("callback");    }}

Spring MVC 3.2 introduced Servlet 3 based asynchronous request processing. Instead ofreturning a value, as usual, a controller method can now return ajava.util.concurrent.Callable and produce the return value from a Spring MVC managed thread.Meanwhile the main Servlet container thread is exited and released and allowed to process otherrequests. Spring MVC invokes theCallable in a separate thread with the help of aTaskExecutor and when theCallable returns, the request is dispatched back to theServlet container to resume processing using the value returned by theCallable. Hereis an example of such a controller method:

@PostMappingpublic Callable<String> processUpload(final MultipartFile file) {returnnew Callable<String>() {public String call()throws Exception {// ...return"someView";        }    };}

Another option is for the controller method to return an instance ofDeferredResult. In thiscase the return value will also be produced from any thread, i.e. one thatis not managed by Spring MVC. For example the result may be produced in response to someexternal event such as a JMS message, a scheduled task, and so on. Here is an exampleof such a controller method:

@RequestMapping("/quotes")@ResponseBodypublic DeferredResult<String> quotes() {    DeferredResult<String> deferredResult =new DeferredResult<String>();// Save the deferredResult somewhere..return deferredResult;}// In some other thread...deferredResult.setResult(data);

This may be difficult to understand without any knowledge of the Servlet 3.0asynchronous request processing features. It would certainly help to read upon that. Here are a few basic facts about the underlying mechanism:

With the above in mind, the following is the sequence of events for async requestprocessing with aCallable:

The sequence forDeferredResult is very similar except it’s up to theapplication to produce the asynchronous result from any thread:

For further background on the motivation for async request processing andwhen or why to use it please readthisblog post series.

@RequestMapping("/events")public ResponseBodyEmitter handle() {    ResponseBodyEmitter emitter =new ResponseBodyEmitter();// Save the emitter somewhere..return emitter;}// In some other threademitter.send("Hello once");// and again later onemitter.send("Hello again");// and done at some pointemitter.complete();

@RequestMapping("/download")public StreamingResponseBody handle() {returnnew StreamingResponseBody() {@Overridepublicvoid writeTo(OutputStream outputStream)throws IOException {// write...        }    };}

<web-appxmlns="http://java.sun.com/xml/ns/javaee"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"http://java.sun.com/xml/ns/javaeehttp://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"version="3.0">    ...</web-app>

<web-appxmlns="http://java.sun.com/xml/ns/javaee"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="            http://java.sun.com/xml/ns/javaee            http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"version="3.0"><filter><filter-name>Spring OpenEntityManagerInViewFilter</filter-name><filter-class>org.springframework.~.OpenEntityManagerInViewFilter</filter-class><async-supported>true</async-supported></filter><filter-mapping><filter-name>Spring OpenEntityManagerInViewFilter</filter-name><url-pattern>/*</url-pattern><dispatcher>REQUEST</dispatcher><dispatcher>ASYNC</dispatcher></filter-mapping></web-app>

Thespring-test module offers first class support for testing annotated controllers.SeeSection 15.6, “Spring MVC Test Framework”.

• interceptors List of interceptors to use.HandlerInterceptors are discussed inSection 22.4.1, “Intercepting requests with a HandlerInterceptor”.
• defaultHandler Default handler to use, when this handler mapping does not result ina matching handler.
• order Based on the value of the order property (see theorg.springframework.core.Ordered interface), Spring sorts all handler mappingsavailable in the context and applies the first matching handler.
• alwaysUseFullPath Iftrue , Spring uses the full path within the current Servletcontext to find an appropriate handler. Iffalse (the default), the path within thecurrent Servlet mapping is used. For example, if a Servlet is mapped using/testing/* and thealwaysUseFullPath property is set to true,/testing/viewPage.html is used, whereas if the property is set to false,/viewPage.html is used.
• urlDecode Defaults totrue, as of Spring 2.5. If you prefer to compare encodedpaths, set this flag tofalse. However, theHttpServletRequest always exposes theServlet path in decoded form. Be aware that the Servlet path will not match whencompared with encoded paths.

Spring’s handler mapping mechanism includes handler interceptors, which are useful whenyou want to apply specific functionality to certain requests, for example, checking fora principal.

Interceptors located in the handler mapping must implementHandlerInterceptor from theorg.springframework.web.servlet package. This interface defines three methods:preHandle(..) is calledbefore the actual handler is executed;postHandle(..) iscalledafter the handler is executed; andafterCompletion(..) is calledafterthe complete request has finished. These three methods should provide enoughflexibility to do all kinds of preprocessing and postprocessing.

ThepreHandle(..) method returns a boolean value. You can use this method to break orcontinue the processing of the execution chain. When this method returnstrue, thehandler execution chain will continue; when it returns false, theDispatcherServletassumes the interceptor itself has taken care of requests (and, for example, rendered anappropriate view) and does not continue executing the other interceptors and the actualhandler in the execution chain.

Interceptors can be configured using theinterceptors property, which is present onallHandlerMapping classes extending fromAbstractHandlerMapping. This is shown inthe example below:

<beans><beanid="handlerMapping"class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping"><propertyname="interceptors"><list><refbean="officeHoursInterceptor"/></list></property></bean><beanid="officeHoursInterceptor"class="samples.TimeBasedAccessInterceptor"><propertyname="openingTime"value="9"/><propertyname="closingTime"value="18"/></bean></beans>

package samples;publicclass TimeBasedAccessInterceptorextends HandlerInterceptorAdapter {privateint openingTime;privateint closingTime;publicvoid setOpeningTime(int openingTime) {this.openingTime = openingTime;    }publicvoid setClosingTime(int closingTime) {this.closingTime = closingTime;    }publicboolean preHandle(HttpServletRequest request, HttpServletResponse response,            Object handler)throws Exception {        Calendar cal = Calendar.getInstance();int hour = cal.get(HOUR_OF_DAY);if (openingTime <= hour && hour < closingTime) {return true;        }        response.sendRedirect("http://host.com/outsideOfficeHours.html");return false;    }}

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

	Note
	When using theRequestMappingHandlerMapping the actual handler is an instance ofHandlerMethod which identifies the specific controller method that will be invoked.

As you can see, the Spring adapter classHandlerInterceptorAdapter makes it easier toextend theHandlerInterceptor interface.

	Tip
	In the example above, the configured interceptor will apply to all requests handled withannotated controller methods. If you want to narrow down the URL paths to which aninterceptor applies, you can use the MVC namespace or the MVC Java config, or declarebean instances of typeMappedInterceptor to do that. SeeSection 22.16.1, “Enabling the MVC Java Config or the MVC XML Namespace”.

Note that thepostHandle method ofHandlerInterceptor is not always ideally suited foruse with@ResponseBody andResponseEntity methods. In such cases anHttpMessageConverterwrites to and commits the response beforepostHandle is called which makes it impossibleto change the response, for example to add a header. Instead an application can implementResponseBodyAdvice and either declare it as an@ControllerAdvice bean or configure itdirectly onRequestMappingHandlerAdapter.

As discussed inSection 22.3, “Implementing Controllers”, all handler methods in the Spring Web MVCcontrollers must resolve to a logical view name, either explicitly (e.g., by returning aString,View, orModelAndView) or implicitly (i.e., based on conventions). Viewsin 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 ofexamples follow.

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

<beanid="viewResolver"class="org.springframework.web.servlet.view.UrlBasedViewResolver"><propertyname="viewClass"value="org.springframework.web.servlet.view.JstlView"/><propertyname="prefix"value="/WEB-INF/jsp/"/><propertyname="suffix"value=".jsp"/></bean>

When returningtest as a logical view name, this view resolver forwards the request totheRequestDispatcher that will send the request to/WEB-INF/jsp/test.jsp.

When you combine different view technologies in a web application, you can use theResourceBundleViewResolver:

<beanid="viewResolver"class="org.springframework.web.servlet.view.ResourceBundleViewResolver"><propertyname="basename"value="views"/><propertyname="defaultParentView"value="parentView"/></bean>

TheResourceBundleViewResolver inspects theResourceBundle identified by thebasename, 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 asthe 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 propertiesfile "extend". This way you can specify a default view class, for example.

	Note
	Subclasses ofAbstractCachingViewResolver cache view instances that they resolve.Caching improves performance of certain view technologies. It’s possible to turn off thecache by setting thecache property tofalse. Furthermore, if you must refresh acertain view at runtime (for example when a Velocity template is modified), you can usetheremoveFromCache(String viewName, Locale loc) method.

Spring supports multiple view resolvers. Thus you can chain resolvers and, for example,override specific views in certain circumstances. You chain view resolvers by addingmore than one resolver to your application context and, if necessary, by setting theorder property to specify ordering. Remember, the higher the order property, the laterthe view resolver is positioned in the chain.

In the following example, the chain of view resolvers consists of two resolvers, anInternalResourceViewResolver, which is always automatically positioned as the lastresolver in the chain, and anXmlViewResolver for specifying Excel views. Excel viewsare not supported by theInternalResourceViewResolver.

<beanid="jspViewResolver"class="org.springframework.web.servlet.view.InternalResourceViewResolver"><propertyname="viewClass"value="org.springframework.web.servlet.view.JstlView"/><propertyname="prefix"value="/WEB-INF/jsp/"/><propertyname="suffix"value=".jsp"/></bean><beanid="excelViewResolver"class="org.springframework.web.servlet.view.XmlViewResolver"><propertyname="order"value="1"/><propertyname="location"value="/WEB-INF/views.xml"/></bean><!-- in views.xml --><beans><beanname="report"class="org.springframework.example.ReportExcelView"/></beans>

If a specific view resolver does not result in a view, Spring examines the context forother view resolvers. If additional view resolvers exist, Spring continues to inspectthem until a view is resolved. If no view resolver returns a view, Spring throws aServletException.

The contract of a view resolver specifies that a view resolvercan return null toindicate the view could not be found. Not all view resolvers do this, however, becausein some cases, the resolver simply cannot detect whether or not the view exists. Forexample, theInternalResourceViewResolver uses theRequestDispatcher internally, anddispatching is the only way to figure out if a JSP exists, but this action can onlyexecute once. The same holds for theVelocityViewResolver and some others. Check thejavadocs of the specific view resolver to see whether it reports non-existing views.Thus, putting anInternalResourceViewResolver in the chain in a place other thanthe last results in the chain not being fully inspected, because theInternalResourceViewResolver willalways return a view!

As mentioned previously, a controller typically returns a logical view name, which aview resolver resolves to a particular view technology. For view technologies such asJSPs that are processed through the Servlet or JSP engine, this resolution is usuallyhandled through the combination ofInternalResourceViewResolver andInternalResourceView, which issues an internal forward or include via the ServletAPI’sRequestDispatcher.forward(..) method orRequestDispatcher.include() method.For other view technologies, such as Velocity, XSLT, and so on, the view itself writesthe content directly to the response stream.

It is sometimes desirable to issue an HTTP redirect back to the client, before the viewis rendered. This is desirable, for example, when one controller has been called withPOST data, and the response is actually a delegation to another controller (forexample on a successful form submission). In this case, a normal internal forward willmean that the other controller will also see the samePOST data, which is potentiallyproblematic if it can confuse it with other expected data. Another reason to perform aredirect before displaying the result is to eliminate the possibility of the usersubmitting the form data multiple times. In this scenario, the browser will first sendan initialPOST; it will then receive a response to redirect to a different URL; andfinally the browser will perform a subsequentGET for the URL named in the redirectresponse. Thus, from the perspective of the browser, the current page does not reflectthe result of aPOST but rather of aGET. The end effect is that there is no way theuser can accidentally re-POST the same data by performing a refresh. The refreshforces aGET of the result page, not a resend of the initialPOST data.

@PostMapping("/files/{path}")public String upload(...) {// ...return"redirect:files/{path}";}

TheContentNegotiatingViewResolver does not resolve views itself but rather delegatesto other view resolvers, selecting the view that resembles the representation requestedby the client. Two strategies exist for a client to request a representation from theserver:

	Note
	One issue with theAccept header is that it is impossible to set it in a web browserwithin HTML. For example, in Firefox, it is fixed to: Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 For this reason it is common to see the use of a distinct URI for each representationwhen developing browser based web applications.

To support multiple representations of a resource, Spring provides theContentNegotiatingViewResolver to resolve a view based on the file extension orAccept header of the HTTP request.ContentNegotiatingViewResolver does not performthe view resolution itself but instead delegates to a list of view resolvers that youspecify through the bean propertyViewResolvers.

TheContentNegotiatingViewResolver selects an appropriateView to handle the requestby comparing the request media type(s) with the media type (also known asContent-Type) supported by theView associated with each of itsViewResolvers. ThefirstView in the list that has a compatibleContent-Type returns the representationto the client. If a compatible view cannot be supplied by theViewResolver chain, thenthe list of views specified through theDefaultViews property will be consulted. Thislatter option is appropriate for singletonViews that can render an appropriaterepresentation of the current resource regardless of the logical view name. TheAcceptheader may include wild cards, for exampletext/*, in which case aView whoseContent-Type wastext/xml is a compatible match.

To support custom resolution of a view based on a file extension, use aContentNegotiationManager: seeSection 22.16.6, “Content Negotiation”.

Here is an example configuration of aContentNegotiatingViewResolver:

<beanclass="org.springframework.web.servlet.view.ContentNegotiatingViewResolver"><propertyname="viewResolvers"><list><beanclass="org.springframework.web.servlet.view.BeanNameViewResolver"/><beanclass="org.springframework.web.servlet.view.InternalResourceViewResolver"><propertyname="prefix"value="/WEB-INF/jsp/"/><propertyname="suffix"value=".jsp"/></bean></list></property><propertyname="defaultViews"><list><beanclass="org.springframework.web.servlet.view.json.MappingJackson2JsonView"/></list></property></bean><beanid="content"class="com.foo.samples.rest.SampleContentAtomView"/>

TheInternalResourceViewResolver handles the translation of view names and JSP pages,while theBeanNameViewResolver returns a view based on the name of a bean. (See"Resolving views with the ViewResolver interface" for moredetails on how Spring looks up and instantiates a view.) In this example, thecontentbean is a class that inherits fromAbstractAtomFeedView, which returns an Atom RSSfeed. For more information on creating an Atom Feed representation, see the section AtomViews.

In the above configuration, if a request is made with an.html extension, the viewresolver looks for a view that matches thetext/html media type. TheInternalResourceViewResolver provides the matching view fortext/html. If therequest is made with the file extension.atom, the view resolver looks for a view thatmatches theapplication/atom+xml media type. This view is provided by theBeanNameViewResolver that maps to theSampleContentAtomView if the view namereturned iscontent. If the request is made with the file extension.json, theMappingJackson2JsonView instance from theDefaultViews list will be selectedregardless of the view name. Alternatively, client requests can be made without a fileextension but with theAccept header set to the preferred media-type, and the sameresolution of request to views would occur.

	Note
	If `ContentNegotiatingViewResolver’s list of ViewResolvers is not configuredexplicitly, 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 formhttp://localhost/content.atom orhttp://localhost/content with anAccept header ofapplication/atom+xml is shown below.

@Controllerpublicclass ContentController {private List<SampleContent> contentList =new ArrayList<SampleContent>();@GetMapping("/content")public ModelAndView getContent() {        ModelAndView mav =new ModelAndView();        mav.setViewName("content");        mav.addObject("sampleContentList", contentList);return mav;    }}

The concept of flash attributes exists in many other Web frameworks and has proven to beexposed sometimes to concurrency issues. This is because by definition flash attributesare to be stored until the next request. However the very "next" request may not be theintended recipient but another asynchronous request (e.g. polling or resource requests)in which case the flash attributes are removed too early.

To reduce the possibility of such issues,RedirectView automatically "stamps"FlashMap instances with the path and query parameters of the target redirect URL. Inturn the defaultFlashMapManager matches that information to incoming requests whenlooking up the "input"FlashMap.

This does not eliminate the possibility of a concurrency issue entirely but neverthelessreduces it greatly with information that is already available in the redirect URL.Therefore the use of flash attributes is recommended mainly for redirect scenarios .

Spring MVC also provides a mechanism for building links to controller methods. For example, given:

@Controller@RequestMapping("/hotels/{hotel}")publicclass BookingController {@GetMapping("/bookings/{booking}")public String getBooking(@PathVariable Long booking) {// ...    }}

You can prepare a link by referring to the method by name:

UriComponents uriComponents = MvcUriComponentsBuilder    .fromMethodName(BookingController.class,"getBooking",21).buildAndExpand(42);URI uri = uriComponents.encode().toUri();

In the above example we provided actual method argument values, in this case the long value 21,to be used as a path variable and inserted into the URL. Furthermore, we provided thevalue 42 in order to fill in any remaining URI variables such as the "hotel" variable inheritedfrom the type-level request mapping. If the method had more arguments you can supply null forarguments not needed for the URL. In general only@PathVariable and@RequestParam argumentsare relevant for constructing the URL.

There are additional ways to useMvcUriComponentsBuilder. For example you can use a techniqueakin to mock testing through proxies to avoid referring to the controller method by name(the example assumes static import ofMvcUriComponentsBuilder.on):

UriComponents uriComponents = MvcUriComponentsBuilder    .fromMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42);URI uri = uriComponents.encode().toUri();

The above examples use static methods inMvcUriComponentsBuilder. Internally they relyonServletUriComponentsBuilder to prepare a base URL from the scheme, host, port,context path and servlet path of the current request. This works well in most cases,however sometimes it may be insufficient. For example you may be outside the context ofa request (e.g. a batch process that prepares links) or perhaps you need to insert a pathprefix (e.g. a locale prefix that was removed from the request path and needs to bere-inserted into links).

For such cases you can use the static "fromXxx" overloaded methods that accept aUriComponentsBuilder to use base URL. Or you can create an instance ofMvcUriComponentsBuilderwith a base URL and then use the instance-based "withXxx" methods. For example:

UriComponentsBuilder base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en");MvcUriComponentsBuilder builder = MvcUriComponentsBuilder.relativeTo(base);builder.withMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42);URI uri = uriComponents.encode().toUri();

As a request goes through proxies such as load balancers the host, port, andscheme may change presenting a challenge for applications that need to create linksto resources since the links should reflect the host, port, and scheme of theoriginal request as seen from a client perspective.

RFC 7239 defines the "Forwarded" HTTP headerfor proxies to use to provide information about the original request. There are alsoother non-standard headers in use such as "X-Forwarded-Host", "X-Forwarded-Port",and "X-Forwarded-Proto".

BothServletUriComponentsBuilder andMvcUriComponentsBuilder detect, extract, and useinformation from the "Forwarded" header, or from "X-Forwarded-Host", "X-Forwarded-Port",and "X-Forwarded-Proto" if "Forwarded" is not present, so that the resulting links reflectthe original request.

TheForwardedHeaderFilter provides an alternative to do the same once and globally forthe entire application. The filter wraps the request in order to overlay host, port, andscheme information and also "hides" any forwarded headers for subsequent processing.

Note that there are security considerations when using forwarded headers as explainedin Section 8 of RFC 7239. At the application level it is difficult to determine whetherforwarded headers can be trusted or not. This is why the network upstream should beconfigured correctly to filter out untrusted forwarded headers from the outside.

Applications that don’t have a proxy and don’t need to use forwarded headers canconfigure theForwardedHeaderFilter to remove and ignore such headers.

You can also build links to annotated controllers from views such as JSP, Thymeleaf,FreeMarker. This can be done using thefromMappingName method inMvcUriComponentsBuilderwhich refers to mappings by name.

Every@RequestMapping is assigned a default name based on the capital letters of theclass and the full method name. For example, the methodgetFoo in classFooControlleris assigned the name "FC#getFoo". This strategy can be replaced or customized by creatingan instance ofHandlerMethodMappingNamingStrategy and plugging it into yourRequestMappingHandlerMapping. The default strategy implementation also looks at thename attribute on@RequestMapping and uses that if present. That means if the defaultmapping name assigned conflicts with another (e.g. overloaded methods) you can assigna name explicitly on the@RequestMapping.

	Note
	The assigned request mapping names are logged at TRACE level on startup.

The Spring JSP tag library provides a function calledmvcUrl that can be used toprepare links to controller methods based on this mechanism.

For example given:

@RequestMapping("/people/{id}/addresses")publicclass PersonAddressController {@RequestMapping("/{country}")public HttpEntity getAddress(@PathVariable String country) { ... }}

You can prepare a link from a JSP as follows:

<%@ taglib uri="http://www.springframework.org/tags" prefix="s" %>...<a href="${s:mvcUrl('PAC#getAddress').arg(0,'US').buildAndExpand('123')}">Get Address</a>

The above example relies on themvcUrl JSP function declared in the Spring tag library(i.e. META-INF/spring.tld). For more advanced cases (e.g. a custom base URL as explainedin the previous section), it is easy to define your own function, or use a custom tag file,in order to use a specific instance ofMvcUriComponentsBuilder with a custom base URL.

In addition to obtaining the client’s locale, it is often useful to know their time zone.TheLocaleContextResolver interface offers an extension toLocaleResolver that allowsresolvers to provide a richerLocaleContext, which may include time zone information.

When available, the user’sTimeZone can be obtained using theRequestContext.getTimeZone() method. Time zone information will automatically be usedby Date/TimeConverter andFormatter objects registered with Spring’sConversionService.

This locale resolver inspects theaccept-language header in the request that was sentby the client (e.g., a web browser). Usually this header field contains the locale ofthe client’s operating system.Note that this resolver does not support time zoneinformation.

This locale resolver inspects aCookie that might exist on the client to see if aLocale orTimeZone is specified. If so, it uses the specified details. Using theproperties of this locale resolver, you can specify the name of the cookie as well as themaximum age. Find below an example of defining aCookieLocaleResolver.

<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>

TheSessionLocaleResolver allows you to retrieveLocale andTimeZone from thesession that might be associated with the user’s request. In contrast toCookieLocaleResolver, this strategy stores locally chosen locale settings in theServlet container’sHttpSession. As a consequence, those settings are just temporaryfor each session and therefore lost when each session terminates.

Note that there is no direct relationship with external session management mechanismssuch as the Spring Session project. ThisSessionLocaleResolver will simply evaluate andmodify correspondingHttpSession attributes against the currentHttpServletRequest.

You can enable changing of locales by adding theLocaleChangeInterceptor to one of thehandler mappings (seeSection 22.4, “Handler mappings”). It will detect a parameter in the requestand change the locale. It callssetLocale() on theLocaleResolver that also existsin the context. The following example shows that calls to all*.view resourcescontaining a parameter namedsiteLanguage will now change the locale. So, for example,a request for the following URL,http://www.sf.net/home.view?siteLanguage=nl willchange the site language to Dutch.

<beanid="localeChangeInterceptor"class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor"><propertyname="paramName"value="siteLanguage"/></bean><beanid="localeResolver"class="org.springframework.web.servlet.i18n.CookieLocaleResolver"/><beanid="urlMapping"class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping"><propertyname="interceptors"><list><refbean="localeChangeInterceptor"/></list></property><propertyname="mappings"><value>/**/*.view=someController</value></property></bean>

You can apply Spring Web MVC framework themes to set the overall look-and-feel of yourapplication, thereby enhancing user experience. A theme is a collection of staticresources, typically style sheets and images, that affect the visual style of theapplication.

To use themes in your web application, you must set up an implementation of theorg.springframework.ui.context.ThemeSource interface. TheWebApplicationContextinterface extendsThemeSource but delegates its responsibilities to a dedicatedimplementation. By default the delegate will be anorg.springframework.ui.context.support.ResourceBundleThemeSource implementation thatloads properties files from the root of the classpath. To use a customThemeSourceimplementation or to configure the base name prefix of theResourceBundleThemeSource,you can register a bean in the application context with the reserved namethemeSource.The web application context automatically detects a bean with that name and uses it.

When using theResourceBundleThemeSource, a theme is defined in a simple propertiesfile. The properties file lists the resources that make up the theme. Here is an example:

styleSheet=/themes/cool/style.cssbackground=/themes/cool/img/coolBg.jpg

The keys of the properties are the names that refer to the themed elements from viewcode. For a JSP, you typically do this using thespring:theme custom tag, which isvery similar to thespring:message tag. The following JSP fragment uses the themedefined in the previous example to customize the look and feel:

<%@taglibprefix="spring"uri="http://www.springframework.org/tags"%><html><head><linkrel="stylesheet"href="<spring:theme code='styleSheet'/>"type="text/css"/></head><bodystyle="background=<spring:theme code='background'/>">        ...</body></html>

By default, theResourceBundleThemeSource uses an empty base name prefix. As a result,the properties files are loaded from the root of the classpath. Thus you would put thecool.properties theme definition in a directory at the root of the classpath, forexample, in/WEB-INF/classes. TheResourceBundleThemeSource uses the standard Javaresource bundle loading mechanism, allowing for full internationalization of themes. Forexample, we could have a/WEB-INF/classes/cool_nl.properties that references a specialbackground image with Dutch text on it.

After you define themes, as in the preceding section, you decide which theme to use. TheDispatcherServlet will look for a bean namedthemeResolver to find out whichThemeResolver implementation to use. A theme resolver works in much the same way as aLocaleResolver. It detects the theme to use for a particular request and can alsoalter the request’s theme. The following theme resolvers are provided by Spring:

Spring also provides aThemeChangeInterceptor that allows theme changes on everyrequest with a simple request parameter.

Spring’s built-in multipart support handles file uploads in web applications. You enablethis multipart support with pluggableMultipartResolver objects, defined in theorg.springframework.web.multipart package. Spring provides oneMultipartResolverimplementation for use withCommonsFileUpload and another for use with Servlet 3.0 multipart request parsing.

By default, Spring does no multipart handling, because some developers want to handlemultiparts themselves. You enable Spring multipart handling by adding a multipartresolver to the web application’s context. Each request is inspected to see if itcontains a multipart. If no multipart is found, the request continues as expected. If amultipart is found in the request, theMultipartResolver that has been declared inyour context is used. After that, the multipart attribute in your request is treatedlike any other attribute.

The following example shows how to use theCommonsMultipartResolver:

<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 multipartresolver to work. In the case of theCommonsMultipartResolver, you need to usecommons-fileupload.jar.

When the SpringDispatcherServlet detects a multi-part request, it activates theresolver that has been declared in your context and hands over the request. The resolverthen wraps the currentHttpServletRequest into aMultipartHttpServletRequest thatsupports multipart file uploads. Using theMultipartHttpServletRequest, you can getinformation about the multiparts contained by this request and actually get access tothe multipart files themselves in your controllers.

In order to use Servlet 3.0 based multipart parsing, you need to mark theDispatcherServlet with a"multipart-config" section inweb.xml, or with ajavax.servlet.MultipartConfigElement in programmatic Servlet registration, or in caseof a custom Servlet class possibly with ajavax.servlet.annotation.MultipartConfigannotation on your Servlet class. Configuration settings such as maximum sizes orstorage locations need to be applied at that Servlet registration level as Servlet 3.0does not allow for those settings to be done from the MultipartResolver.

Once Servlet 3.0 multipart parsing has been enabled in one of the above mentioned waysyou can add theStandardServletMultipartResolver to your Spring configuration:

<beanid="multipartResolver"class="org.springframework.web.multipart.support.StandardServletMultipartResolver"></bean>

After theMultipartResolver completes its job, the request is processed like anyother. 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 toencode the form as multipart request:

<html><head><title>Upload a file please</title></head><body><h1>Please upload a file</h1><formmethod="post"action="/form"enctype="multipart/form-data"><inputtype="text"name="name"/><inputtype="file"name="file"/><inputtype="submit"/></form></body></html>

The next step is to create a controller that handles the file upload. This controller isvery similar to anormal annotated@Controller, except that weuseMultipartHttpServletRequest orMultipartFile in the method parameters:

@Controllerpublicclass FileUploadController {@PostMapping("/form")public String handleFormUpload(@RequestParam("name") String name,@RequestParam("file") MultipartFile file) {if (!file.isEmpty()) {byte[] bytes = file.getBytes();// store the bytes somewherereturn"redirect:uploadSuccess";        }return"redirect:uploadFailure";    }}

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

When using Servlet 3.0 multipart parsing you can also usejavax.servlet.http.Part forthe method parameter:

@Controllerpublicclass FileUploadController {@PostMapping("/form")public String handleFormUpload(@RequestParam("name") String name,@RequestParam("file") Part file) {        InputStream inputStream = file.getInputStream();// store bytes from uploaded file somewherereturn"redirect:uploadSuccess";    }}

Multipart requests can also be submitted from non-browser clients in a RESTful servicescenario. All of the above examples and configuration apply here as well. However,unlike browsers that typically submit files and simple form fields, a programmaticclient can also send more complex data of a specific content type — for example amultipart request with a file and second part with JSON formatted data:

POST /someUrlContent-Type: multipart/mixed--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7VpContent-Disposition: form-data; name="meta-data"Content-Type: application/json; charset=UTF-8Content-Transfer-Encoding: 8bit{"name": "value"}--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7VpContent-Disposition: form-data; name="file-data"; filename="file.properties"Content-Type: text/xmlContent-Transfer-Encoding: 8bit... File Data ...

You could access the part named "meta-data" with a@RequestParam("meta-data") Stringmetadata controller method argument. However, you would probably prefer to accept astrongly typed object initialized from the JSON formatted data in the body of therequest part, very similar to the way@RequestBody converts the body of anon-multipart request to a target object with the help of anHttpMessageConverter.

You can use the@RequestPart annotation instead of the@RequestParam annotation forthis purpose. It allows you to have the content of a specific multipart passed throughanHttpMessageConverter taking into consideration the'Content-Type' header of themultipart:

@PostMapping("/someUrl")public String onSubmit(@RequestPart("meta-data") MetaData metadata,        @RequestPart("file-data") MultipartFile file) {// ...}

Notice howMultipartFile method arguments can be accessed with@RequestParam or with@RequestPart interchangeably. However, the@RequestPart("meta-data") MetaData methodargument in this case is read as JSON content based on its'Content-Type' header andconverted with the help of theMappingJackson2HttpMessageConverter.

SpringHandlerExceptionResolver implementations deal with unexpected exceptions thatoccur during controller execution. AHandlerExceptionResolver somewhat resembles theexception mappings you can define in the web application descriptorweb.xml. However,they provide a more flexible way to do so. For example they provide information aboutwhich handler was executing when the exception was thrown. Furthermore, a programmaticway of handling exceptions gives you more options for responding appropriately beforethe request is forwarded to another URL (the same end result as when you use the Servletspecific exception mappings).

Besides implementing theHandlerExceptionResolver interface, which is only a matter ofimplementing theresolveException(Exception, Handler) method and returning aModelAndView, you may also use the providedSimpleMappingExceptionResolver or create@ExceptionHandler methods. TheSimpleMappingExceptionResolver enables you to takethe class name of any exception that might be thrown and map it to a view name. This isfunctionally equivalent to the exception mapping feature from the Servlet API, but it isalso possible to implement more finely grained mappings of exceptions from differenthandlers. The@ExceptionHandler annotation on the other hand can be used on methodsthat should be invoked to handle an exception. Such methods may be defined locallywithin an@Controller or may apply to many@Controller classes when defined within an@ControllerAdvice class. The following sections explain this in more detail.

TheHandlerExceptionResolver interface and theSimpleMappingExceptionResolverimplementations allow you to map Exceptions to specific views declaratively along withsome optional Java logic before forwarding to those views. However, in some cases,especially when relying on@ResponseBody methods rather than on view resolution, itmay be more convenient to directly set the status of the response and optionally writeerror content to the body of the response.

You can do that with@ExceptionHandler methods. When declared within a controller suchmethods apply to exceptions raised by@RequestMapping methods of that controller (orany of its subclasses). You can also declare an@ExceptionHandler method within an@ControllerAdvice class in which case it handles exceptions from@RequestMappingmethods from many controllers. Below is an example of a controller-local@ExceptionHandler method:

@Controllerpublicclass SimpleController {// @RequestMapping methods omitted ...@ExceptionHandler(IOException.class)public ResponseEntity<String> handleIOException(IOException ex) {// prepare responseEntityreturn responseEntity;    }}

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

Tip

For@ExceptionHandler methods, a root exception match will be preferred to justmatching a cause of the current exception, among the handler methods of a particularcontroller or advice bean. However, a cause match on a higher-priority@ControllerAdvicewill still be preferred to a any match (whether root or cause level) on a lower-priorityadvice bean. As a consequence, when using a multi-advice arrangement, please declare yourprimary root exception mappings on a prioritized advice bean with a corresponding order!

Much like standard controller methods annotated with a@RequestMapping annotation, themethod arguments and return values of@ExceptionHandler methods can be flexible. Forexample, theHttpServletRequest can be accessed in Servlet environments and thePortletRequest in Portlet environments. The return type can be aString, which isinterpreted as a view name, aModelAndView object, aResponseEntity, or you can alsoadd the@ResponseBody to have the method return value converted with messageconverters and written to the response stream.

Spring MVC may raise a number of exceptions while processing a request. TheSimpleMappingExceptionResolver can easily map any exception to a default error view asneeded. However, when working with clients that interpret responses in an automated wayyou will want to set specific status code on the response. Depending on the exceptionraised the status code may indicate a client error (4xx) or a server error (5xx).

TheDefaultHandlerExceptionResolver translates Spring MVC exceptions to specific errorstatus codes. It is registered by default with the MVC namespace, the MVC Java config,and also by theDispatcherServlet (i.e. when not using the MVC namespace or Javaconfig). Listed below are some of the exceptions handled by this resolver and thecorresponding status codes:

TheDefaultHandlerExceptionResolver works transparently by setting the status of theresponse. However, it stops short of writing any error content to the body of theresponse while your application may need to add developer-friendly content to everyerror response for example when providing a REST API. You can prepare aModelAndViewand render error content through view resolution — i.e. by configuring aContentNegotiatingViewResolver,MappingJackson2JsonView, and so on. However, you mayprefer to use@ExceptionHandler methods instead.

If you prefer to write error content via@ExceptionHandler methods you can extendResponseEntityExceptionHandler instead. This is a convenient base for@ControllerAdvice classes providing an@ExceptionHandler method to handle standardSpring MVC exceptions and returnResponseEntity. That allows you to customize theresponse and write error content with message converters. See theResponseEntityExceptionHandler javadocs for more details.

A business exception can be annotated with@ResponseStatus. When the exception israised, theResponseStatusExceptionResolver handles it by setting the status of theresponse accordingly. By default theDispatcherServlet registers theResponseStatusExceptionResolver and it is available for use.

When the status of the response is set to an error status code and the body of theresponse is empty, Servlet containers commonly render an HTML formatted error page. Tocustomize the default error page of the container, you can declare an<error-page>element inweb.xml. Up until Servlet 3, that element had to be mapped to a specificstatus code or exception type. Starting with Servlet 3 an error page does not need to bemapped, which effectively means the specified location customizes the default Servletcontainer error page.

<error-page><location>/error</location></error-page>

Note that the actual location for the error page can be a JSP page or some other URLwithin the container including one handled through an@Controller method:

When writing error information, the status code and the error message set on theHttpServletResponse can be accessed through request attributes in a controller:

@Controllerpublicclass ErrorController {@RequestMapping(path = "/error", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)@ResponseBodypublic 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;    }}

or in a JSP:

<%@pagecontentType="application/json"pageEncoding="UTF-8"%>{status:<%=request.getAttribute("javax.servlet.error.status_code")%>,reason:<%=request.getAttribute("javax.servlet.error.message")%>}

TheControllerClassNameHandlerMapping class is aHandlerMapping implementation thatuses a convention to determine the mapping between request URLs and theControllerinstances that are to handle those requests.

Consider the following simpleController implementation. Take special notice of thename of the class.

publicclassViewShoppingCartControllerimplements Controller {public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) {// the implementation is not hugely important for this example...    }}

Here is a snippet from the corresponding Spring Web MVC configuration file:

<beanclass="org.springframework.web.servlet.mvc.support.ControllerClassNameHandlerMapping"/><beanid="viewShoppingCart"><!-- inject dependencies as required... --></bean>

TheControllerClassNameHandlerMapping finds all of the various handler (orController) beans defined in its application context and stripsController off thename 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-casedController class names.)

In the case ofMultiActionController handler classes, the mappings generated areslightly more complex. TheController names in the following examples are assumed tobeMultiActionController implementations:

If you follow the convention of naming yourController implementations asxxxController, theControllerClassNameHandlerMapping saves you the tedium ofdefining and maintaining a potentiallylooooongSimpleUrlHandlerMapping (orsuchlike).

TheControllerClassNameHandlerMapping class extends theAbstractHandlerMapping baseclass so you can defineHandlerInterceptor instances and everything else just as youwould with many otherHandlerMapping implementations.

TheModelMap class is essentially a glorifiedMap that can make adding objects thatare to be displayed in (or on) aView adhere to a common naming convention. Considerthe followingController implementation; notice that objects are added to theModelAndView without any associated name specified.

publicclass DisplayShoppingCartControllerimplements Controller {public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) {        List cartItems =// get a List of CartItem objects        User user =// get the User doing the shopping        ModelAndView mav =new ModelAndView("displayShoppingCart"); <-- the logical view name        mav.addObject(cartItems); <-- look ma, no name, just the object        mav.addObject(user); <-- and again ma!return mav;    }}

TheModelAndView class uses aModelMap class that is a customMap implementationthat automatically generates a key for an object when an object is added to it. Thestrategy for determining the name for an added object is, in the case of a scalar objectsuch asUser, to use the short class name of the object’s class. The followingexamples are names that are generated for scalar objects put into aModelMap instance.

The strategy for generating a name after adding aSet or aList is to peek into thecollection, take the short class name of the first object in the collection, and usethat withList appended to the name. The same applies to arrays although with arraysit is not necessary to peek into the array contents. A few examples will make thesemantics of name generation for collections clearer:

TheRequestToViewNameTranslator interface determines a logicalView name when nosuch logical view name is explicitly supplied. It has just one implementation, theDefaultRequestToViewNameTranslator class.

TheDefaultRequestToViewNameTranslator maps request URLs to logical view names, aswith this example:

publicclass RegistrationControllerimplements Controller {public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) {// process the request...        ModelAndView mav =new ModelAndView();// add data as necessary to the model...return mav;// notice that no View or logical view name has been set    }}

<?xml version="1.0" encoding="UTF-8"?><beansxmlns="http://www.springframework.org/schema/beans"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="        http://www.springframework.org/schema/beans        http://www.springframework.org/schema/beans/spring-beans.xsd"><!-- this bean with the well known name generates view names for us --><beanid="viewNameTranslator"class="org.springframework.web.servlet.view.DefaultRequestToViewNameTranslator"/><beanclass="x.y.RegistrationController"><!-- inject dependencies as necessary --></bean><!-- maps request URLs to Controller names --><beanclass="org.springframework.web.servlet.mvc.support.ControllerClassNameHandlerMapping"/><beanid="viewResolver"class="org.springframework.web.servlet.view.InternalResourceViewResolver"><propertyname="prefix"value="/WEB-INF/jsp/"/><propertyname="suffix"value=".jsp"/></bean></beans>

Notice how in the implementation of thehandleRequest(..) method noView or logicalview name is ever set on theModelAndView that is returned. TheDefaultRequestToViewNameTranslator is tasked with generating alogical view namefrom the URL of the request. In the case of the aboveRegistrationController, which isused in conjunction with theControllerClassNameHandlerMapping, a request URL ofhttp://localhost/registration.html results in a logical view name ofregistrationbeing generated by theDefaultRequestToViewNameTranslator. This logical view name isthen resolved into the/WEB-INF/jsp/registration.jsp view by theInternalResourceViewResolver bean.

	Tip
	You do not need to define aDefaultRequestToViewNameTranslator bean explicitly. If youlike the default settings of theDefaultRequestToViewNameTranslator, you can rely onthe Spring Web MVCDispatcherServlet to instantiate an instance of this class if oneis not explicitly configured.

Of course, if you need to change the default settings, then you do need to configureyour ownDefaultRequestToViewNameTranslator bean explicitly. Consult the comprehensiveDefaultRequestToViewNameTranslator javadocs for details on the various propertiesthat can be configured.

Spring Web MVC supports many use cases and ways to configure "Cache-Control" headers foran application. WhileRFC 7234 Section 5.2.2completely describes that header and its possible directives, there are several ways toaddress the most common cases.

Spring Web MVC uses a configuration convention in several of its APIs:setCachePeriod(int seconds):

TheCacheControl builderclass simply describes the available "Cache-Control" directives and makes it easier tobuild your own HTTP caching strategy. Once built, aCacheControl instance can then beaccepted as an argument in several Spring Web MVC APIs.

// Cache for an hour - "Cache-Control: max-age=3600"CacheControl ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS);// Prevent caching - "Cache-Control: no-store"CacheControl ccNoStore = CacheControl.noStore();// Cache for ten days in public and private caches,// public caches should not transform the response// "Cache-Control: max-age=864000, public, no-transform"CacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS)                                    .noTransform().cachePublic();

Static resources should be served with appropriate'Cache-Control' and conditionalheaders for optimal performance.Configuring aResourceHttpRequestHandler for servingstatic resources not only natively writes'Last-Modified' headers by reading a file’smetadata, but also'Cache-Control' headers if properly configured.

You can set thecachePeriod attribute on aResourceHttpRequestHandler or useaCacheControl instance, which supports more specific directives:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("/resources/**")                .addResourceLocations("/public-resources/")                .setCacheControl(CacheControl.maxAge(1, TimeUnit.HOURS).cachePublic());    }}

And in XML:

<mvc:resourcesmapping="/resources/**"location="/public-resources/"><mvc:cache-controlmax-age="3600"cache-public="true"/></mvc:resources>

Controllers can support'Cache-Control','ETag', and/or'If-Modified-Since' HTTP requests;this is indeed recommended if a'Cache-Control' header is to be set on the response.This involves calculating a lastModifiedlong and/or an Etag value for a given request,comparing it against the'If-Modified-Since' request header value, and potentially returninga response with status code 304 (Not Modified).

As described inthe section called “Using HttpEntity”, controllers can interact with the request/response usingHttpEntity types. Controllers returningResponseEntity can include HTTP caching informationin responses like this:

@GetMapping("/book/{id}")public ResponseEntity<Book> showBook(@PathVariable Long id) {    Book book = findBook(id);    String version = book.getVersion();return ResponseEntity                .ok()                .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS))                .eTag(version)// lastModified is also available                .body(book);}

Doing this will not only include'ETag' and'Cache-Control' headers in the response, it willalso convert theresponse to anHTTP 304 Not Modified response with an empty body if the conditional headers sent by the clientmatch the caching information set by the Controller.

An@RequestMapping method may also wish to support the same behavior.This can be achieved as follows:

@RequestMappingpublic String myHandleMethod(WebRequest webRequest, Model model) {long lastModified =// 1. application-specific calculationif (request.checkNotModified(lastModified)) {// 2. shortcut exit - no further processing necessaryreturn null;    }// 3. or otherwise further request processing, actually preparing content    model.addAttribute(...);return"myViewName";}

There are two key elements here: callingrequest.checkNotModified(lastModified) andreturningnull. The former sets the appropriate response status and headersbefore it returnstrue.The latter, in combination with the former, causes Spring MVC to do no furtherprocessing of the request.

Note that there are 3 variants for this:

When receiving conditional'GET'/'HEAD' requests,checkNotModified will checkthat the resource has not been modified and if so, it will result in aHTTP 304 Not Modifiedresponse. In case of conditional'POST'/'PUT'/'DELETE' requests,checkNotModifiedwill check that the resource has not been modified and if it has been, it will result in aHTTP 409 Precondition Failed response to prevent concurrent modifications.

Support for ETags is provided by the Servlet filterShallowEtagHeaderFilter. It is aplain Servlet Filter, and thus can be used in combination with any web framework. TheShallowEtagHeaderFilter filter creates so-called shallow ETags (as opposed to deepETags, more about that later).The filter caches the content of the rendered JSP (orother content), generates an MD5 hash over that, and returns that as an ETag header inthe response. The next time a client sends a request for the same resource, it uses thathash as theIf-None-Match value. The filter detects this, renders the view again, andcompares the two hashes. If they are equal, a304 is returned.

Note that this strategy saves network bandwidth but not CPU, as the full response must becomputed for each request. Other strategies at the controller level (described above) cansave network bandwidth and avoid computation.

This filter has awriteWeakETag parameter that configures the filter to write Weak ETags,like this:W/"02a2d595e6ed9a0b24f027f2b63b134d6", as defined inRFC 7232 Section 2.3.

You configure theShallowEtagHeaderFilter inweb.xml:

<filter><filter-name>etagFilter</filter-name><filter-class>org.springframework.web.filter.ShallowEtagHeaderFilter</filter-class><!-- Optional parameter that configures the filter to write weak ETags    <init-param>        <param-name>writeWeakETag</param-name>        <param-value>true</param-value>    </init-param>    --></filter><filter-mapping><filter-name>etagFilter</filter-name><servlet-name>petclinic</servlet-name></filter-mapping>

Or in Servlet 3.0+ environments,

publicclass MyWebAppInitializerextends AbstractDispatcherServletInitializer {// ...@Overrideprotected Filter[] getServletFilters() {returnnew Filter[] {new ShallowEtagHeaderFilter() };    }}

SeeSection 22.15, “Code-based Servlet container initialization” for more details.

To enable MVC Java config add the annotation@EnableWebMvc to one of your@Configuration classes:

@Configuration@EnableWebMvcpublicclass WebConfig {}

To achieve the same in XML use themvc:annotation-driven element in yourDispatcherServlet context (or in your root context if you have no DispatcherServletcontext defined):

<?xml version="1.0" encoding="UTF-8"?><beansxmlns="http://www.springframework.org/schema/beans"xmlns:mvc="http://www.springframework.org/schema/mvc"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="        http://www.springframework.org/schema/beans        http://www.springframework.org/schema/beans/spring-beans.xsd        http://www.springframework.org/schema/mvc        http://www.springframework.org/schema/mvc/spring-mvc.xsd"><mvc:annotation-driven/></beans>

The above registers aRequestMappingHandlerMapping, aRequestMappingHandlerAdapter,and anExceptionHandlerExceptionResolver (among others) in support of processingrequests with annotated controller methods using annotations such as@RequestMapping,@ExceptionHandler, and others.

It also enables the following:

SeeSection 22.16.12, “Message Converters” for more information about how to customize thesedefault converters.

Note

Jackson JSON and XML converters are created usingObjectMapper instances created byJackson2ObjectMapperBuilderin order to provide a better default configuration. This builder customizes Jackson’s default properties with the following ones: DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES is disabled. MapperFeature.DEFAULT_VIEW_INCLUSION is disabled. It also automatically registers the following well-known modules if they are detected on the classpath: jackson-datatype-jdk7: support for Java 7 types likejava.nio.file.Path. jackson-datatype-joda: support for Joda-Time types. jackson-datatype-jsr310: support for Java 8 Date & Time API types. jackson-datatype-jdk8: support for other Java 8 types likeOptional.

To customize the default configuration in Java you simply implement theWebMvcConfigurer interface or more likely extend the classWebMvcConfigurerAdapterand override the methods you need:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {// Override configuration methods...}

To customize the default configuration of<mvc:annotation-driven/> check whatattributes and sub-elements it supports. You can view theSpring MVC XML schema or use the codecompletion feature of your IDE to discover what attributes and sub-elements areavailable.

By default formatters forNumber andDate types are installed, including support forthe@NumberFormat and@DateTimeFormat annotations. Full support for the Joda Timeformatting library is also installed if Joda Time is present on the classpath. Toregister custom formatters and converters, override theaddFormatters method:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid addFormatters(FormatterRegistry registry) {// ...    }}

In the MVC namespace the same defaults apply when<mvc:annotation-driven> is added.To register custom formatters and converters simply supply aConversionService:

<?xml version="1.0" encoding="UTF-8"?><beansxmlns="http://www.springframework.org/schema/beans"xmlns:mvc="http://www.springframework.org/schema/mvc"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="        http://www.springframework.org/schema/beans        http://www.springframework.org/schema/beans/spring-beans.xsd        http://www.springframework.org/schema/mvc        http://www.springframework.org/schema/mvc/spring-mvc.xsd"><mvc:annotation-drivenconversion-service="conversionService"/><beanid="conversionService"class="org.springframework.format.support.FormattingConversionServiceFactoryBean"><propertyname="converters"><set><beanclass="org.example.MyConverter"/></set></property><propertyname="formatters"><set><beanclass="org.example.MyFormatter"/><beanclass="org.example.MyAnnotationFormatterFactory"/></set></property><propertyname="formatterRegistrars"><set><beanclass="org.example.MyFormatterRegistrar"/></set></property></bean></beans>

	Note
	SeeSection 9.6.4, “FormatterRegistrar SPI” and theFormattingConversionServiceFactoryBeanfor more information on when to use FormatterRegistrars.

Spring provides aValidator interface that can be used for validation in all layersof an application. In Spring MVC you can configure it for use as a globalValidator instance, to be usedwhenever an@Valid or@Validated controller method argument is encountered, and/or as a localValidator within a controller through an@InitBinder method. Global and local validatorinstances can be combined to provide composite validation.

Spring alsosupports JSR-303/JSR-349 Bean ValidationviaLocalValidatorFactoryBean which adapts the Springorg.springframework.validation.Validatorinterface to the Bean Validationjavax.validation.Validator contract. This class can beplugged into Spring MVC as a global validator as described next.

By default use of@EnableWebMvc or<mvc:annotation-driven> automatically registers BeanValidation support in Spring MVC through theLocalValidatorFactoryBean when a Bean Validationprovider such as Hibernate Validator is detected on the classpath.

Note

Sometimes it’s convenient to have aLocalValidatorFactoryBean injected into a controlleror another class. The easiest way to do that is to declare your own@Bean and also mark itwith@Primary in order to avoid a conflict with the one provided with the MVC Java config. If you prefer to use the one from the MVC Java config, you’ll need to override themvcValidator method fromWebMvcConfigurationSupport and declare the method to explicitlyreturnLocalValidatorFactory rather thanValidator. SeeSection 22.16.13, “Advanced Customizations with MVC Java Config”for information on how to switch to extend the provided configuration.

Alternatively you can configure your own globalValidator instance:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublic Validator getValidator(); {// return "global" validator    }}

and in XML:

<?xml version="1.0" encoding="UTF-8"?><beansxmlns="http://www.springframework.org/schema/beans"xmlns:mvc="http://www.springframework.org/schema/mvc"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="        http://www.springframework.org/schema/beans        http://www.springframework.org/schema/beans/spring-beans.xsd        http://www.springframework.org/schema/mvc        http://www.springframework.org/schema/mvc/spring-mvc.xsd"><mvc:annotation-drivenvalidator="globalValidator"/></beans>

To combine global with local validation, simply add one or more local validator(s):

@Controllerpublicclass MyController {@InitBinderprotectedvoid initBinder(WebDataBinder binder) {        binder.addValidators(new FooValidator());    }}

With this minimal configuration any time an@Valid or@Validated method argument is encountered, itwill be validated by the configured validators. Any validation violations will automaticallybe exposed as errors in theBindingResult accessible as a method argument and also renderablein Spring MVC HTML views.

You can configureHandlerInterceptors orWebRequestInterceptors to be applied to allincoming requests or restricted to specific URL path patterns.

An example of registering interceptors in Java:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid addInterceptors(InterceptorRegistry registry) {        registry.addInterceptor(new LocaleInterceptor());        registry.addInterceptor(new ThemeInterceptor()).addPathPatterns("/**").excludePathPatterns("/admin/**");        registry.addInterceptor(new SecurityInterceptor()).addPathPatterns("/secure/*");    }}

And in XML use the<mvc:interceptors> element:

<mvc:interceptors><beanclass="org.springframework.web.servlet.i18n.LocaleChangeInterceptor"/><mvc:interceptor><mvc:mappingpath="/**"/><mvc:exclude-mappingpath="/admin/**"/><beanclass="org.springframework.web.servlet.theme.ThemeChangeInterceptor"/></mvc:interceptor><mvc:interceptor><mvc:mappingpath="/secure/*"/><beanclass="org.example.SecurityInterceptor"/></mvc:interceptor></mvc:interceptors>

You can configure how Spring MVC determines the requested media types from the request.The available options are to check the URL path for a file extension, check the"Accept" header, a specific query parameter, or to fall back on a default contenttype when nothing is requested. By default the path extension in the request URIis checked first and the "Accept" header is checked second.

The MVC Java config and the MVC namespace registerjson,xml,rss,atom bydefault if corresponding dependencies are on the classpath. Additionalpath extension-to-media type mappings may also be registered explicitly and thatalso has the effect of whitelisting them as safe extensions for the purpose of RFDattack detection (seethe section called “Suffix Pattern Matching and RFD” for more detail).

Below is an example of customizing content negotiation options through the MVC Java config:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid configureContentNegotiation(ContentNegotiationConfigurer configurer) {        configurer.mediaType("json", MediaType.APPLICATION_JSON);    }}

In the MVC namespace, the<mvc:annotation-driven> element has acontent-negotiation-manager attribute, which expects aContentNegotiationManagerthat in turn can be created with aContentNegotiationManagerFactoryBean:

<mvc:annotation-drivencontent-negotiation-manager="contentNegotiationManager"/><beanid="contentNegotiationManager"class="org.springframework.web.accept.ContentNegotiationManagerFactoryBean"><propertyname="mediaTypes"><value>            json=application/json            xml=application/xml</value></property></bean>

If not using the MVC Java config or the MVC namespace, you’ll need to create an instanceofContentNegotiationManager and use it to configureRequestMappingHandlerMappingfor request mapping purposes, andRequestMappingHandlerAdapter andExceptionHandlerExceptionResolver for content negotiation purposes.

Note thatContentNegotiatingViewResolver now can also be configured with aContentNegotiationManager, so you can use one shared instance throughout Spring MVC.

In more advanced cases, it may be useful to configure multipleContentNegotiationManager instances that in turn may contain customContentNegotiationStrategy implementations. For example you could configureExceptionHandlerExceptionResolver with aContentNegotiationManager that alwaysresolves the requested media type to"application/json". Or you may want to plug acustom strategy that has some logic to select a default content type (e.g. either XML orJSON) if no content types were requested.

This is a shortcut for defining aParameterizableViewController that immediatelyforwards to a view when invoked. Use it in static cases when there is no Java controllerlogic to execute before the view generates the response.

An example of forwarding a request for"/" to a view called"home" in Java:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid addViewControllers(ViewControllerRegistry registry) {        registry.addViewController("/").setViewName("home");    }}

And the same in XML use the<mvc:view-controller> element:

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

The MVC config simplifies the registration of view resolvers.

The following is a Java config example that configures content negotiation viewresolution using FreeMarker HTML templates and Jackson as a defaultView forJSON rendering:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid configureViewResolvers(ViewResolverRegistry registry) {        registry.enableContentNegotiation(new MappingJackson2JsonView());        registry.jsp();    }}

And the same in XML:

<mvc:view-resolvers><mvc:content-negotiation><mvc:default-views><beanclass="org.springframework.web.servlet.view.json.MappingJackson2JsonView"/></mvc:default-views></mvc:content-negotiation><mvc:jsp/></mvc:view-resolvers>

Note however that FreeMarker, Velocity, Tiles, Groovy Markup and script templates also requireconfiguration of the underlying view technology.

The MVC namespace provides dedicated elements. For example with FreeMarker:

<mvc:view-resolvers><mvc:content-negotiation><mvc:default-views><beanclass="org.springframework.web.servlet.view.json.MappingJackson2JsonView"/></mvc:default-views></mvc:content-negotiation><mvc:freemarkercache="false"/></mvc:view-resolvers><mvc:freemarker-configurer><mvc:template-loader-pathlocation="/freemarker"/></mvc:freemarker-configurer>

In Java config simply add the respective "Configurer" bean:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid configureViewResolvers(ViewResolverRegistry registry) {        registry.enableContentNegotiation(new MappingJackson2JsonView());        registry.freeMarker().cache(false);    }@Beanpublic FreeMarkerConfigurer freeMarkerConfigurer() {        FreeMarkerConfigurer configurer =new FreeMarkerConfigurer();        configurer.setTemplateLoaderPath("/WEB-INF/");return configurer;    }}

This option allows static resource requests following a particular URL pattern to beserved by aResourceHttpRequestHandler from any of a list ofResource locations.This provides a convenient way to serve static resources from locations other than theweb application root, including locations on the classpath. Thecache-period propertymay be used to set far future expiration headers (1 year is the recommendation ofoptimization tools such as Page Speed and YSlow) so that they will be more efficientlyutilized by the client. The handler also properly evaluates theLast-Modified header(if present) so that a304 status code will be returned as appropriate, avoidingunnecessary overhead for resources that are already cached by the client. For example,to serve resource requests with a URL pattern of/resources/** from apublic-resources directory within the web application root you would use:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("/resources/**").addResourceLocations("/public-resources/");    }}

And the same in XML:

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

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

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("/resources/**").addResourceLocations("/public-resources/").setCachePeriod(31556926);    }}

And in XML:

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

For more details, seeHTTP caching support for static resources.

Themapping attribute must be an Ant pattern that can be used bySimpleUrlHandlerMapping, and thelocation attribute must specify one or more validresource directory locations. Multiple resource locations may be specified using acomma-separated list of values. The locations specified will be checked in the specifiedorder for the presence of the resource for any given request. For example, to enable theserving 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 use:

@EnableWebMvc@Configurationpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("/resources/**")                .addResourceLocations("/","classpath:/META-INF/public-web-resources/");    }}

And in XML:

<mvc:resourcesmapping="/resources/**"location="/, classpath:/META-INF/public-web-resources/"/>

When serving resources that may change when a new version of the application isdeployed it is recommended that you incorporate a version string into the mappingpattern used to request the resources so that you may force clients to request thenewly deployed version of your application’s resources. Support for versioned URLs isbuilt into the framework and can be enabled by configuring a resource chainon the resource handler. The chain consists of one moreResourceResolverinstances followed by one or moreResourceTransformer instances. Together theycan provide arbitrary resolution and transformation of resources.

The built-inVersionResourceResolver can be configured with different strategies.For example aFixedVersionStrategy can use a property, a date, or other as the version.AContentVersionStrategy uses an MD5 hash computed from the content of the resource(known as "fingerprinting" URLs). Note that theVersionResourceResolver will automaticallyuse the resolved version strings as HTTP ETag header values when serving resources.

ContentVersionStrategy is a good default choice to use except in cases whereit cannot be used (e.g. with JavaScript module loaders). You can configuredifferent version strategies against different patterns as shown below. Keep in mindalso that computing content-based versions is expensive and therefore resource chaincaching should be enabled in production.

Java config example;

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("/resources/**")                .addResourceLocations("/public-resources/")                .resourceChain(true)                .addResolver(new VersionResourceResolver().addContentVersionStrategy("/**"));    }}

XML example:

<mvc:resourcesmapping="/resources/**"location="/public-resources/"><mvc:resource-chain><mvc:resource-cache/><mvc:resolvers><mvc:version-resolver><mvc:content-version-strategypatterns="/**"/></mvc:version-resolver></mvc:resolvers></mvc:resource-chain></mvc:resources>

In order for the above to work the application must alsorender URLs with versions. The easiest way to do that is to configure theResourceUrlEncodingFilter which wraps the response and overrides itsencodeURL method.This will work in JSPs, FreeMarker, Velocity, and any other view technology that callsthe responseencodeURL method. Alternatively, an application can also inject anduse directly theResourceUrlProvider bean, which is automatically declared with the MVCJava config and the MVC namespace.

Webjars are also supported withWebJarsResourceResolver, which is automatically registeredwhen the"org.webjars:webjars-locator" library is on classpath. This resolver allowsthe resource chain to resolve version agnostic libraries from HTTP GET requests"GET /jquery/jquery.min.js" will return resource"/jquery/1.2.0/jquery.min.js".It also works by rewriting resource URLs in templates<script src="/jquery/jquery.min.js"/> → <script src="/jquery/1.2.0/jquery.min.js"/>.

This allows for mapping theDispatcherServlet to "/" (thus overriding the mappingof the container’s default Servlet), while still allowing static resource requests to behandled by the container’s default Servlet. It configures aDefaultServletHttpRequestHandler with a URL mapping of "/**" and the lowest priorityrelative to other URL mappings.

This handler will forward all requests to the default Servlet. Therefore it is importantthat it remains last in the order of all other URLHandlerMappings. That will be thecase if you use<mvc:annotation-driven> or alternatively if you are setting up yourown customizedHandlerMapping instance be sure to set itsorder property to a valuelower than that of theDefaultServletHttpRequestHandler, which isInteger.MAX_VALUE.

To enable the feature using the default setup use:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {        configurer.enable();    }}

Or in XML:

<mvc:default-servlet-handler/>

The caveat to overriding the "/" Servlet mapping is that theRequestDispatcher for thedefault Servlet must be retrieved by name rather than by path. TheDefaultServletHttpRequestHandler will attempt to auto-detect the default Servlet forthe container at startup time, using a list of known names for most of the major Servletcontainers (including Tomcat, Jetty, GlassFish, JBoss, Resin, WebLogic, and WebSphere).If the default Servlet has been custom configured with a different name, or if adifferent 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:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {        configurer.enable("myCustomDefaultServlet");    }}

Or in XML:

<mvc:default-servlet-handlerdefault-servlet-name="myCustomDefaultServlet"/>

This allows customizing various settings related to URL mapping and path matching.For details on the individual options check out thePathMatchConfigurer API.

Below is an example in Java config:

@Configuration@EnableWebMvcpublicclass WebConfigextends WebMvcConfigurerAdapter {@Overridepublicvoid configurePathMatch(PathMatchConfigurer configurer) {        configurer            .setUseSuffixPatternMatch(true)            .setUseTrailingSlashMatch(false)            .setUseRegisteredSuffixPatternMatch(true)            .setPathMatcher(antPathMatcher())            .setUrlPathHelper(urlPathHelper());    }@Beanpublic UrlPathHelper urlPathHelper() {//...    }@Beanpublic PathMatcher antPathMatcher() {//...    }}

And the same in XML, use the<mvc:path-matching> element:

<mvc:annotation-driven><mvc:path-matchingsuffix-pattern="true"trailing-slash="false"registered-suffixes-only="true"path-helper="pathHelper"path-matcher="pathMatcher"/></mvc:annotation-driven><beanid="pathHelper"class="org.example.app.MyPathHelper"/><beanid="pathMatcher"class="org.example.app.MyPathMatcher"/>

Customization ofHttpMessageConverter can be achieved in Java config by overridingconfigureMessageConverters()if you want to replace the default converters created by Spring MVC, or by overridingextendMessageConverters()if you just want to customize them or add additional converters to the default ones.

Below is an example that adds Jackson JSON and XML converters with a customizedObjectMapper instead of default ones:

@Configuration@EnableWebMvcpublicclass WebConfigurationextends WebMvcConfigurerAdapter {@Overridepublicvoid configureMessageConverters(List<HttpMessageConverter<?>> converters) {        Jackson2ObjectMapperBuilder builder =new Jackson2ObjectMapperBuilder()                .indentOutput(true)                .dateFormat(new SimpleDateFormat("yyyy-MM-dd"))                .modulesToInstall(new ParameterNamesModule());        converters.add(new MappingJackson2HttpMessageConverter(builder.build()));        converters.add(new MappingJackson2XmlHttpMessageConverter(builder.xml().build()));    }}

In this example,Jackson2ObjectMapperBuilder is used to create a common configuration forbothMappingJackson2HttpMessageConverter andMappingJackson2XmlHttpMessageConverter withindentation enabled, a customized date format and the registration ofjackson-module-parameter-namesthat adds support for accessing parameter names (feature added in Java 8).

	Note
	Enabling indentation with Jackson XML support requireswoodstox-core-asldependency in addition tojackson-dataformat-xml one.

Other interesting Jackson modules are available:

It is also possible to do the same in XML:

<mvc:annotation-driven><mvc:message-converters><beanclass="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter"><propertyname="objectMapper"ref="objectMapper"/></bean><beanclass="org.springframework.http.converter.xml.MappingJackson2XmlHttpMessageConverter"><propertyname="objectMapper"ref="xmlMapper"/></bean></mvc:message-converters></mvc:annotation-driven><beanid="objectMapper"class="org.springframework.http.converter.json.Jackson2ObjectMapperFactoryBean"p:indentOutput="true"p:simpleDateFormat="yyyy-MM-dd"p:modulesToInstall="com.fasterxml.jackson.module.paramnames.ParameterNamesModule"/><beanid="xmlMapper"parent="objectMapper"p:createXmlMapper="true"/>

As you can see from the above examples, MVC Java config and the MVC namespace providehigher level constructs that do not require deep knowledge of the underlying beanscreated for you. Instead it helps you to focus on your application needs. However, atsome point you may need more fine-grained control or you may simply wish to understandthe underlying configuration.

The first step towards more fine-grained control is to see the underlying beans createdfor you. In MVC Java config you can see the javadocs and the@Bean methods inWebMvcConfigurationSupport. The configuration in this class is automatically importedthrough the@EnableWebMvc annotation. In fact if you open@EnableWebMvc you can seethe@Import statement.

The next step towards more fine-grained control is to customize a property on one of thebeans created inWebMvcConfigurationSupport or perhaps to provide your own instance.This requires two things — remove the@EnableWebMvc annotation in order to preventthe import and then extend fromDelegatingWebMvcConfiguration, a subclass ofWebMvcConfigurationSupport.Here is an example:

@Configurationpublicclass WebConfigextends DelegatingWebMvcConfiguration {@Overridepublicvoid addInterceptors(InterceptorRegistry registry){// ...    }@Override@Beanpublic RequestMappingHandlerAdapter requestMappingHandlerAdapter() {// Create or let "super" create the adapter// Then customize one of its properties    }}

	Note
	An application should have only one configuration extendingDelegatingWebMvcConfigurationor a single@EnableWebMvc annotated class, since they both register the same underlyingbeans. Modifying beans in this way does not prevent you from using any of the higher-levelconstructs shown earlier in this section.WebMvcConfigurerAdapter subclasses andWebMvcConfigurer implementations are still being used.

Fine-grained control over the configuration created for you is a bit harder with the MVCnamespace.

If you do need to do that, rather than replicating the configuration it provides,consider configuring aBeanPostProcessor that detects the bean you want to customizeby type and then modifying its properties as necessary. For example:

@Componentpublicclass MyPostProcessorimplements BeanPostProcessor {public Object postProcessBeforeInitialization(Object bean, String name)throws BeansException {if (beaninstanceof RequestMappingHandlerAdapter) {// Modify properties of the adapter        }    }}

Note thatMyPostProcessor needs to be included in an<component scan/> in order forit to be detected or if you prefer you can declare it explicitly with an XML beandeclaration.