27.1 The ‘Spring Web MVC framework’
The Spring Web MVC framework (often referred to as simply ‘Spring MVC’) is a rich ‘model view controller’ web framework. Spring MVC lets you create special @Controller
or @RestController
beans to handle incoming HTTP requests. Methods in your controller are mapped to HTTP using @RequestMapping
annotations.
Here is a typical example @RestController
to serve JSON data:
_@RestController_ _@RequestMapping(value="/users")_ public class MyRestController { _@RequestMapping(value="/{user}", method=RequestMethod.GET)_ public User getUser(_@PathVariable_ Long user) { // ... } _@RequestMapping(value="/{user}/customers", method=RequestMethod.GET)_ List<Customer> getUserCustomers(_@PathVariable_ Long user) { // ... } _@RequestMapping(value="/{user}", method=RequestMethod.DELETE)_ public User deleteUser(_@PathVariable_ Long user) { // ... } }
Spring MVC is part of the core Spring Framework and detailed information is available in the reference documentation. There are also several guides available at spring.io/guides that cover Spring MVC.
27.1.1 Spring MVC auto-configuration
Spring Boot provides auto-configuration for Spring MVC that works well with most applications.
The auto-configuration adds the following features on top of Spring’s defaults:
- Inclusion of
ContentNegotiatingViewResolver
andBeanNameViewResolver
beans. - Support for serving static resources, including support for WebJars (see below).
- Automatic registration of
Converter
,GenericConverter
,Formatter
beans. - Support for
HttpMessageConverters
(see below). - Automatic registration of
MessageCodesResolver
(see below). - Static
index.html
support. - Custom
Favicon
support. - Automatic use of a
ConfigurableWebBindingInitializer
bean (see below).
If you want to keep Spring Boot MVC features, and you just want to add additional MVC configuration (interceptors, formatters, view controllers etc.) you can add your own @Configuration
class of type WebMvcConfigurerAdapter
, but without @EnableWebMvc
. If you wish to provide custom instances of RequestMappingHandlerMapping
, RequestMappingHandlerAdapter
or ExceptionHandlerExceptionResolver
you can declare a WebMvcRegistrationsAdapter
instance providing such components.
If you want to take complete control of Spring MVC, you can add your own @Configuration
annotated with @EnableWebMvc
.
27.1.2 HttpMessageConverters
Spring MVC uses the HttpMessageConverter
interface to convert HTTP requests and responses. Sensible defaults are included out of the box, for example Objects can be automatically converted to JSON (using the Jackson library) or XML (using the Jackson XML extension if available, else using JAXB). Strings are encoded using UTF-8
by default.
If you need to add or customize converters you can use Spring Boot’s HttpMessageConverters
class:
import org.springframework.boot.autoconfigure.web.HttpMessageConverters; import org.springframework.context.annotation.*; import org.springframework.http.converter.*; _@Configuration_ public class MyConfiguration { _@Bean_ public HttpMessageConverters customConverters() { HttpMessageConverter<?> additional = ... HttpMessageConverter<?> another = ... return new HttpMessageConverters(additional, another); } }
Any HttpMessageConverter
bean that is present in the context will be added to the list of converters. You can also override default converters that way.
27.1.3 Custom JSON Serializers and Deserializers
If you’re using Jackson to serialize and deserialize JSON data, you might want to write your own JsonSerializer
and JsonDeserializer
classes. Custom serializers are usually registered with Jackson via a Module, but Spring Boot provides an alternative @JsonComponent
annotation which makes it easier to directly register Spring Beans.
You can use @JsonComponent
directly on JsonSerializer
or JsonDeserializer
implementations. You can also use it on classes that contains serializers/deserializers as inner-classes. For example:
import java.io.*; import com.fasterxml.jackson.core.*; import com.fasterxml.jackson.databind.*; import org.springframework.boot.jackson.*; _@JsonComponent_ public class Example { public static class Serializer extends JsonSerializer<SomeObject> { // ... } public static class Deserializer extends JsonDeserializer<SomeObject> { // ... } }
All @JsonComponent
beans in the ApplicationContext
will be automatically registered with Jackson, and since @JsonComponent
is meta-annotated with @Component
, the usual component-scanning rules apply.
Spring Boot also provides JsonObjectSerializer
and JsonObjectDeserializer
base classes which provide useful alternatives to the standard Jackson versions when serializing Objects. See the Javadoc for details.
27.1.4 MessageCodesResolver
Spring MVC has a strategy for generating error codes for rendering error messages from binding errors: MessageCodesResolver
. Spring Boot will create one for you if you set the spring.mvc.message-codes-resolver.format
property PREFIX_ERROR_CODE
or POSTFIX_ERROR_CODE
(see the enumeration in DefaultMessageCodesResolver.Format
).
27.1.5 Static Content
By default Spring Boot will serve static content from a directory called /static
(or /public
or /resources
or /META-INF/resources
) in the classpath or from the root of the ServletContext
. It uses the ResourceHttpRequestHandler
from Spring MVC so you can modify that behavior by adding your own WebMvcConfigurerAdapter
and overriding the addResourceHandlers
method.
In a stand-alone web application the default servlet from the container is also enabled, and acts as a fallback, serving content from the root of the ServletContext
if Spring decides not to handle it. Most of the time this will not happen (unless you modify the default MVC configuration) because Spring will always be able to handle requests through the DispatcherServlet
.
You can customize the static resource locations using spring.resources.staticLocations
(replacing the default values with a list of directory locations). If you do this the default welcome page detection will switch to your custom locations, so if there is an index.html
in any of your locations on startup, it will be the home page of the application.
In addition to the ‘standard’ static resource locations above, a special case is made for Webjars content. Any resources with a path in /webjars/**
will be served from jar files if they are packaged in the Webjars format.
Tip | |
---|---|
Do not use the src/main/webapp directory if your application will be packaged as a jar. Although this directory is a common standard, it will only work with war packaging and it will be silently ignored by most build tools if you generate a jar. |
Spring Boot also supports advanced resource handling features provided by Spring MVC, allowing use cases such as cache busting static resources or using version agnostic URLs for Webjars.
To use version agnostic URLs for Webjars, simply add the webjars-locator
dependency. Then declare your Webjar, taking jQuery for example, as "/webjars/jquery/dist/jquery.min.js"
which results in "/webjars/jquery/x.y.z/dist/jquery.min.js"
where x.y.z
is the Webjar version.
Note | |
---|---|
If you are using JBoss, you’ll need to declare the webjars-locator-jboss-vfs dependency instead of the webjars-locator ; otherwise all Webjars resolve as a 404 . |
To use cache bursting, the following configuration will configure a cache busting solution for all static resources, effectively adding a content hash in URLs, such as <link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>
:
spring.resources.chain.strategy.content.enabled=true spring.resources.chain.strategy.content.paths=/**
Note | |
---|---|
Links to resources are rewritten at runtime in template, thanks to a ResourceUrlEncodingFilter , auto-configured for Thymeleaf, Velocity and FreeMarker. You should manually declare this filter when using JSPs. Other template engines aren’t automatically supported right now, but can be with custom template macros/helpers and the use of the ResourceUrlProvider . |
When loading resources dynamically with, for example, a JavaScript module loader, renaming files is not an option. That’s why other strategies are also supported and can be combined. A "fixed" strategy will add a static version string in the URL, without changing the file name:
spring.resources.chain.strategy.content.enabled=true spring.resources.chain.strategy.content.paths=/** spring.resources.chain.strategy.fixed.enabled=true spring.resources.chain.strategy.fixed.paths=/js/lib/ spring.resources.chain.strategy.fixed.version=v12
With this configuration, JavaScript modules located under "/js/lib/"
will use a fixed versioning strategy "/v12/js/lib/mymodule.js"
while other resources will still use the content one <link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>
.
See ResourceProperties
for more of the supported options.
Tip | |
---|---|
This feature has been thoroughly described in a dedicated blog post and in Spring Framework’s reference documentation. |
27.1.6 ConfigurableWebBindingInitializer
Spring MVC uses a WebBindingInitializer
to initialize a WebDataBinder
for a particular request. If you create your own ConfigurableWebBindingInitializer
@Bean
, Spring Boot will automatically configure Spring MVC to use it.
27.1.7 Template engines
As well as REST web services, you can also use Spring MVC to serve dynamic HTML content. Spring MVC supports a variety of templating technologies including Velocity, FreeMarker and JSPs. Many other templating engines also ship their own Spring MVC integrations.
Spring Boot includes auto-configuration support for the following templating engines:
- FreeMarker
- Groovy
- Thymeleaf
- Velocity (deprecated in 1.4)
- Mustache
Tip | |
---|---|
JSPs should be avoided if possible, there are several known limitations when using them with embedded servlet containers. |
When you’re using one of these templating engines with the default configuration, your templates will be picked up automatically from src/main/resources/templates
.
Tip | |
---|---|
IntelliJ IDEA orders the classpath differently depending on how you run your application. Running your application in the IDE via its main method will result in a different ordering to when you run your application using Maven or Gradle or from its packaged jar. This can cause Spring Boot to fail to find the templates on the classpath. If you’re affected by this problem you can reorder the classpath in the IDE to place the module’s classes and resources first. Alternatively, you can configure the template prefix to search every templates directory on the classpath: classpath*:/templates/ . |
27.1.8 Error Handling
Spring Boot provides an /error
mapping by default that handles all errors in a sensible way, and it is registered as a ‘global’ error page in the servlet container. For machine clients it will produce a JSON response with details of the error, the HTTP status and the exception message. For browser clients there is a ‘whitelabel’ error view that renders the same data in HTML format (to customize it just add a View
that resolves to ‘error’). To replace the default behaviour completely you can implement ErrorController
and register a bean definition of that type, or simply add a bean of type ErrorAttributes
to use the existing mechanism but replace the contents.
Tip | |
---|---|
The BasicErrorController can be used as a base class for a custom ErrorController . This is particularly useful if you want to add a handler for a new content type (the default is to handle text/html specifically and provide a fallback for everything else). To do that just extend BasicErrorController and add a public method with a @RequestMapping that has a produces attribute, and create a bean of your new type. |
You can also define a @ControllerAdvice
to customize the JSON document to return for a particular controller and/or exception type.
_@ControllerAdvice(basePackageClasses = FooController.class)_ public class FooControllerAdvice extends ResponseEntityExceptionHandler { _@ExceptionHandler(YourException.class)_ _@ResponseBody_ ResponseEntity<?> handleControllerException(HttpServletRequest request, Throwable ex) { HttpStatus status = getStatus(request); return new ResponseEntity<>(new CustomErrorType(status.value(), ex.getMessage()), status); } private HttpStatus getStatus(HttpServletRequest request) { Integer statusCode = (Integer) request.getAttribute("javax.servlet.error.status_code"); if (statusCode == null) { return HttpStatus.INTERNAL_SERVER_ERROR; } return HttpStatus.valueOf(statusCode); } }
In the example above, if YourException
is thrown by a controller defined in the same package as FooController
, a json representation of the CustomerErrorType
POJO will be used instead of the ErrorAttributes
representation.
Custom error pages
If you want to display a custom HTML error page for a given status code, you add a file to an /error
folder. Error pages can either be static HTML (i.e. added under any of the static resource folders) or built using templates. The name of the file should be the exact status code or a series mask.
For example, to map 404
to a static HTML file, your folder structure would look like this:
src/ +- main/ +- java/ | + <source code> +- resources/ +- public/ +- error/ | +- 404.html +- <other public assets>
To map all 5xx
errors using a FreeMarker template, you’d have a structure like this:
src/ +- main/ +- java/ | + <source code> +- resources/ +- templates/ +- error/ | +- 5xx.ftl +- <other templates>
For more complex mappings you can also add beans that implement the ErrorViewResolver
interface.
public class MyErrorViewResolver implements ErrorViewResolver { _@Override_ public ModelAndView resolveErrorView(HttpServletRequest request, HttpStatus status, Map<String, Object> model) { // Use the request or status to optionally return a ModelAndView return ... } }
You can also use regular Spring MVC features like @ExceptionHandler
methods and @ControllerAdvice
. The ErrorController
will then pick up any unhandled exceptions.
Mapping error pages outside of Spring MVC
For applications that aren’t using Spring MVC, you can use the ErrorPageRegistrar
interface to directly register ErrorPages
. This abstraction works directly with the underlying embedded servlet container and will work even if you don’t have a Spring MVC DispatcherServlet
.
_@Bean_ public ErrorPageRegistrar errorPageRegistrar(){ return new MyErrorPageRegistrar(); } // ... private static class MyErrorPageRegistrar implements ErrorPageRegistrar { _@Override_ public void registerErrorPages(ErrorPageRegistry registry) { registry.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400")); } }
N.B. if you register an ErrorPage
with a path that will end up being handled by a Filter
(e.g. as is common with some non-Spring web frameworks, like Jersey and Wicket), then the Filter
has to be explicitly registered as an ERROR
dispatcher, e.g.
_@Bean_ public FilterRegistrationBean myFilter() { FilterRegistrationBean registration = new FilterRegistrationBean(); registration.setFilter(new MyFilter()); ... registration.setDispatcherTypes(EnumSet.allOf(DispatcherType.class)); return registration; }
(the default FilterRegistrationBean
does not include the ERROR
dispatcher type).
Error Handling on WebSphere Application Server
When deployed to a servlet container, a Spring Boot uses its error page filter to forward a request with an error status to the appropriate error page. The request can only be forwarded to the correct error page if the response has not already been committed. By default, WebSphere Application Server 8.0 and later commits the response upon successful completion of a servlet’s service method. You should disable this behaviour by setting com.ibm.ws.webcontainer.invokeFlushAfterService
to false
27.1.9 Spring HATEOAS
If you’re developing a RESTful API that makes use of hypermedia, Spring Boot provides auto-configuration for Spring HATEOAS that works well with most applications. The auto-configuration replaces the need to use @EnableHypermediaSupport
and registers a number of beans to ease building hypermedia-based applications including a LinkDiscoverers
(for client side support) and an ObjectMapper
configured to correctly marshal responses into the desired representation. The ObjectMapper
will be customized based on the spring.jackson.*
properties or a Jackson2ObjectMapperBuilder
bean if one exists.
You can take control of Spring HATEOAS’s configuration by using @EnableHypermediaSupport
. Note that this will disable the ObjectMapper
customization described above.
27.1.10 CORS support
Cross-origin resource sharing (CORS) is a W3C specification implemented by most browsers that allows you to specify in a flexible way what kind of cross domain requests are authorized, instead of using some less secure and less powerful approaches like IFRAME or JSONP.
As of version 4.2, Spring MVC supports CORS out of the box. Using controller method CORS configuration with @CrossOrigin
annotations in your Spring Boot application does not require any specific configuration. Global CORS configuration can be defined by registering a WebMvcConfigurer
bean with a customized addCorsMappings(CorsRegistry)
method:
_@Configuration_ public class MyConfiguration { _@Bean_ public WebMvcConfigurer corsConfigurer() { return new WebMvcConfigurerAdapter() { _@Override_ public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/api/**"); } }; } }