Spring Boot is well suited for web application development. You can easily create a
self-contained HTTP server using embedded Tomcat, Jetty, or Undertow. Most web
applications will use the spring-boot-starter-web
module to get up and running quickly.
If you haven’t yet developed a Spring Boot web application you can follow the "Hello World!" example in the Getting started section.
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.
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:
ContentNegotiatingViewResolver
and BeanNameViewResolver
beans.Converter
, GenericConverter
, Formatter
beans.HttpMessageConverters
(see below).MessageCodeResolver
(see below)index.html
support.Favicon
support.If you want to take complete control of Spring MVC, you can add your own @Configuration
annotated with @EnableWebMvc
. 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 @Bean
of type
WebMvcConfigurerAdapter
, but without @EnableWebMvc
.
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.
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
).
By default Spring Boot will serve static content from a folder 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
.
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 |
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:
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 |
---|---|
JSPs should be avoided if possible, there are several known limitations when using them with embedded servlet containers. |
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.
If you want more specific error pages for some conditions, the embedded servlet containers support a uniform Java DSL for customizing the error handling. For example:
@Bean public EmbeddedServletContainerCustomizer containerCustomizer(){ return new MyCustomizer(); } // ... private static class MyCustomizer implements EmbeddedServletContainerCustomizer { @Override public void customize(ConfigurableEmbeddedServletContainer container) { container.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400")); } }
You can also use regular Spring MVC features like
@ExceptionHandler
methods and
@ControllerAdvice
. The ErrorController
will then pick up any unhandled exceptions.
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).
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
If you prefer the JAX-RS programming model for REST endpoints you can use one of the
available implementations instead of Spring MVC. Jersey 1.x and Apache Celtix work
quite well out of the box if you just register their Servlet
or Filter
as a
@Bean
in your application context. Jersey 2.x has some native Spring support so
we also provide auto-configuration support for it in Spring Boot together with a
starter.
To get started with Jersey 2.x just include the spring-boot-starter-jersey
as a
dependency and then you need one @Bean
of type ResourceConfig
in which you register
all the endpoints:
@Component public class JerseyConfig extends ResourceConfig { public JerseyConfig() { register(Endpoint.class); } }
All the registered endpoints should be @Components
with HTTP resource annotations
(@GET
etc.), e.g.
@Component @Path("/hello") public class Endpoint { @GET public String message() { return "Hello"; } }
Since the Endpoint
is a Spring @Component
its lifecycle is managed by Spring and you
can @Autowired
dependencies and inject external configuration with @Value
. The Jersey
servlet will be registered and mapped to /*
by default. You can change the mapping
by adding @ApplicationPath
to your ResourceConfig
.
By default Jersey will be set up as a Servlet in a @Bean
of type
ServletRegistrationBean
named jerseyServletRegistration
. You can disable or override
that bean by creating one of your own with the same name. You can also use a Filter
instead of a Servlet by setting spring.jersey.type=filter
(in which case the @Bean
to
replace or override is jerseyFilterRegistration
). The servlet has an @Order
which you
can set with spring.jersey.filter.order
. Both the Servlet and the Filter registrations
can be given init parameters using spring.jersey.init.*
to specify a map of properties.
There is a Jersey sample so
you can see how to set things up. There is also a Jersey 1.x sample.
Note that in the Jersey 1.x sample that the spring-boot maven plugin has been configured to
unpack some Jersey jars so they can be scanned by the JAX-RS implementation (because the sample
asks for them to be scanned in its Filter
registration). You may need to do the same
if any of your JAX-RS resources are packages as nested jars.
Spring Boot includes support for embedded Tomcat, Jetty, and Undertow servers. Most
developers will simply use the appropriate ‘Starter POM’ to obtain a fully configured
instance. By default the embedded server will listen for HTTP requests on port 8080
.
When using an embedded servlet container you can register Servlets and Filters directly as
Spring beans. This can be particularly convenient if you want to refer to a value from
your application.properties
during configuration.
By default, if the context contains only a single Servlet it will be mapped to /
. In
the case of multiple Servlet beans the bean name will be used as a path prefix. Filters
will map to /*
.
If convention-based mapping is not flexible enough you can use the
ServletRegistrationBean
and FilterRegistrationBean
classes for complete control. You
can also register items directly if your bean implements the ServletContextInitializer
interface.
Under the hood Spring Boot uses a new type of ApplicationContext
for embedded
servlet container support. The EmbeddedWebApplicationContext
is a special
type of WebApplicationContext
that bootstraps itself by searching for a single
EmbeddedServletContainerFactory
bean. Usually a TomcatEmbeddedServletContainerFactory
,
JettyEmbeddedServletContainerFactory
, or UndertowEmbeddedServletContainerFactory
will
have been auto-configured.
![]() | Note |
---|---|
You usually won’t need to be aware of these implementation classes. Most
applications will be auto-configured and the appropriate |
Common servlet container settings can be configured using Spring Environment
properties. Usually you would define the properties in your application.properties
file.
Common server settings include:
server.port
— The listen port for incoming HTTP requests.server.address
— The interface address to bind to.server.sessionTimeout
— A session timeout.See the ServerProperties
class for a complete list.
If you need to configure your embdedded servlet container programmatically you can register
a Spring bean that implements the EmbeddedServletContainerCustomizer
interface.
EmbeddedServletContainerCustomizer
provides access to the
ConfigurableEmbeddedServletContainer
which includes numerous customization setter
methods.
import org.springframework.boot.context.embedded.*; import org.springframework.stereotype.Component; @Component public class CustomizationBean implements EmbeddedServletContainerCustomizer { @Override public void customize(ConfigurableEmbeddedServletContainer container) { container.setPort(9000); } }
If the above customization techniques are too limited, you can register the
TomcatEmbeddedServletContainerFactory
, JettyEmbeddedServletContainerFactory
or
UndertowEmbeddedServletContainerFactory
bean yourself.
@Bean public EmbeddedServletContainerFactory servletContainer() { TomcatEmbeddedServletContainerFactory factory = new TomcatEmbeddedServletContainerFactory(); factory.setPort(9000); factory.setSessionTimeout(10, TimeUnit.MINUTES); factory.addErrorPages(new ErrorPage(HttpStatus.NOT_FOUND, "/notfound.html"); return factory; }
Setters are provided for many configuration options. Several protected method ‘hooks’ are also provided should you need to do something more exotic. See the source code documentation for details.
When running a Spring Boot application that uses an embedded servlet container (and is packaged as an executable archive), there are some limitations in the JSP support.
There is a JSP sample so you can see how to set things up.