27.3 Embedded servlet container support

Spring Boot includes support for embedded Tomcat, Jetty, and Undertow servers. Most developers will simply use the appropriate ‘Starter’ to obtain a fully configured instance. By default the embedded server will listen for HTTP requests on port 8080.

27.3.1 Servlets, Filters, and listeners

When using an embedded servlet container you can register Servlets, Filters and all the listeners from the Servlet spec (e.g. HttpSessionListener) either by using Spring beans or by scanning for Servlet components.

Registering Servlets, Filters, and listeners as Spring beans

Any Servlet, Filter or Servlet *Listener instance that is a Spring bean will be registered with the embedded container. 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, FilterRegistrationBean and ServletListenerRegistrationBean classes for complete control.

27.3.2 Servlet Context Initialization

Embedded servlet containers will not directly execute the Servlet 3.0+ javax.servlet.ServletContainerInitializer interface, or Spring’s org.springframework.web.WebApplicationInitializer interface. This is an intentional design decision intended to reduce the risk that 3rd party libraries designed to run inside a war will break Spring Boot applications.

If you need to perform servlet context initialization in a Spring Boot application, you should register a bean that implements the org.springframework.boot.context.embedded.ServletContextInitializer interface. The single onStartup method provides access to the ServletContext, and can easily be used as an adapter to an existing WebApplicationInitializer if necessary.

Scanning for Servlets, Filters, and listeners

When using an embedded container, automatic registration of @WebServlet, @WebFilter, and @WebListener annotated classes can be enabled using @ServletComponentScan.

	Tip
`@ServletComponentScan` will have no effect in a standalone container, where the container’s built-in discovery mechanisms will be used instead.

27.3.3 The EmbeddedWebApplicationContext

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 `ApplicationContext` and `EmbeddedServletContainerFactory` will be created on your behalf.

27.3.4 Customizing embedded servlet containers

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:

Network settings: listen port for incoming HTTP requests (server.port), interface address to bind to server.address, etc.
Session settings: whether the session is persistent (server.session.persistence), session timeout (server.session.timeout), location of session data (server.session.store-dir) and session-cookie configuration (server.session.cookie.*).
Error management: location of the error page (server.error.path), etc.
SSL
HTTP compression

Spring Boot tries as much as possible to expose common settings but this is not always possible. For those cases, dedicated namespaces offer server-specific customizations (see server.tomcat and server.undertow). For instance, access logs can be configured with specific features of the embedded servlet container.

	Tip
See the `ServerProperties` class for a complete list.

Programmatic customization

If you need to configure your embedded 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);
    }

}

Customizing ConfigurableEmbeddedServletContainer directly

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.

27.3.5 JSP limitations

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.

With Tomcat it should work if you use war packaging, i.e. an executable war will work, and will also be deployable to a standard container (not limited to, but including Tomcat). An executable jar will not work because of a hard coded file pattern in Tomcat.
With Jetty it should work if you use war packaging, i.e. an executable war will work, and will also be deployable to any standard container.
Undertow does not support JSPs.
Creating a custom error.jsp page won’t override the default view for error handling, custom error pages should be used instead.

There is a JSP sample so you can see how to set things up.

27.3 Embedded servlet container support