How Spring Boot Auto‑Configures Embedded Tomcat: A Deep Dive

1. What is Auto‑Configuration

In Spring Boot the spring-boot-autoconfigure module provides many default configurations, known as “auto‑configuration”. It uses Spring’s conditional annotation @Conditional to load configuration based on the classpath.

2. Why Use Auto‑Configuration

It replaces XML configuration; for example, Spring MVC components such as component scanning, dispatcher, and view resolvers are automatically configured, and the embedded Tomcat is set up without manual configuration.

3. Spring Boot Tomcat Auto‑Configuration Details

We analyze Tomcat auto‑configuration from four aspects:

Spring Boot project configuration

Spring Boot project startup

How Spring Boot configures Tomcat

How Spring Boot starts Tomcat

3.1 Spring Boot Project Configuration

The pom.xml includes the following essential sections:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>myproject</artifactId>
    <version>0.0.1‑SNAPSHOT</version>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.3.RELEASE</version>
    </parent>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

The two most important configurations are the <parent> element that sets the Spring Boot version and the spring-boot-starter-web dependency that brings in auto‑configuration.

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.2.3.RELEASE</version>
</parent>

and

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

These bring in spring-web, spring-webmvc, spring-boot-starter-tomcat and other essential modules.

3.2 Spring Boot Project Startup

A typical Spring Boot main class looks like:

@SpringBootApplication
public class RaftApplication {
    public static void main(String[] args) {
        SpringApplication.run(RaftApplication.class, args);
    }
}

The spring-boot-autoconfigure module registers ServletWebServerFactoryAutoConfiguration via spring.factories, which triggers Tomcat auto‑configuration.

3.3 How Tomcat Is Auto‑Configured

The class ServletWebServerFactoryAutoConfiguration is annotated with several conditional annotations:

@Configuration(proxyBeanMethods = false)
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
@ConditionalOnClass(ServletRequest.class)
@ConditionalOnWebApplication(type = Type.SERVLET)
@EnableConfigurationProperties(ServerProperties.class)
@Import({
    ServletWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar.class,
    ServletWebServerFactoryConfiguration.EmbeddedTomcat.class,
    ServletWebServerFactoryConfiguration.EmbeddedJetty.class,
    ServletWebServerFactoryConfiguration.EmbeddedUndertow.class
})
public class ServletWebServerFactoryAutoConfiguration { … }

Key beans include ServletWebServerFactoryCustomizer and a Tomcat‑specific TomcatServletWebServerFactoryCustomizer that are created only when the Tomcat classes are present.

@Bean
public ServletWebServerFactoryCustomizer servletWebServerFactoryCustomizer(ServerProperties serverProperties) {
    return new ServletWebServerFactoryCustomizer(serverProperties);
}

@Bean
@ConditionalOnClass(name = "org.apache.catalina.startup.Tomcat")
public TomcatServletWebServerFactoryCustomizer tomcatServletWebServerFactoryCustomizer(ServerProperties serverProperties) {
    return new TomcatServletWebServerFactoryCustomizer(serverProperties);
}

The static inner class BeanPostProcessorsRegistrar registers synthetic beans such as WebServerFactoryCustomizerBeanPostProcessor and ErrorPageRegistrarBeanPostProcessor.

3.4 How Tomcat Is Started

The TomcatServletWebServerFactory creates a Tomcat instance in its getWebServer method, configuring the base directory, connector, and engine before returning a TomcatWebServer object.

@Override
public WebServer getWebServer(ServletContextInitializer... initializers) {
    Tomcat tomcat = new Tomcat();
    // configure baseDir, connector, engine, etc.
    return getTomcatWebServer(tomcat);
}

During application context refresh, AnnotationConfigServletWebServerApplicationContext calls createWebServer() and later startWebServer(), publishing a ServletWebServerInitializedEvent once Tomcat is running.

4. When Does Tomcat Actually Start?

Spring Boot creates the embedded Tomcat during the onRefresh phase of the application context and starts it in the finishRefresh phase, after all beans have been initialized.

Note: The underlying mechanism of Spring Boot auto‑configuration relies on the @Conditional annotation.