0
# Auto-Configuration
1

2
Automatic configuration classes that set up Tomcat components based on classpath detection and application properties. Spring Boot's auto-configuration system provides convention-over-configuration setup while allowing extensive customization through properties and custom beans.
3

4
## Capabilities
5

6
### ServletWebServerFactoryAutoConfiguration
7

8
Main auto-configuration class for servlet web servers, including Tomcat support. Conditionally creates web server factory beans and customizers.
9

10
```java { .api }
11
/**
12
 * Auto-configuration for servlet web server factories
13
 */
14
@AutoConfiguration
15
@ConditionalOnClass(ServletRequest.class)
16
@ConditionalOnWebApplication(type = WebApplicationType.SERVLET)
17
@EnableConfigurationProperties(ServerProperties.class)
18
@Import({ ServletWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar.class,
19
         ServletWebServerFactoryConfiguration.EmbeddedTomcat.class,
20
         ServletWebServerFactoryConfiguration.EmbeddedJetty.class,
21
         ServletWebServerFactoryConfiguration.EmbeddedUndertow.class })
22
public class ServletWebServerFactoryAutoConfiguration {
23
    
24
    /** Creates servlet web server factory customizer */
25
    @Bean
26
    public ServletWebServerFactoryCustomizer servletWebServerFactoryCustomizer(
27
            ServerProperties serverProperties, 
28
            ObjectProvider<WebListenerRegistrar> webListenerRegistrars,
29
            ObjectProvider<CookieSameSiteSupplier> cookieSameSiteSuppliers);
30
    
31
    /** Creates Tomcat servlet web server factory customizer */
32
    @Bean
33
    @ConditionalOnClass(name = "org.apache.catalina.startup.Tomcat")
34
    public TomcatServletWebServerFactoryCustomizer tomcatServletWebServerFactoryCustomizer(
35
            ServerProperties serverProperties);
36
    
37
    /** Creates forwarded header filter when configured */
38
    @Bean
39
    @ConditionalOnMissingBean
40
    @ConditionalOnProperty(value = "server.forward-headers-strategy", havingValue = "framework")
41
    public FilterRegistrationBean<ForwardedHeaderFilter> forwardedHeaderFilter();
42
}
43
```
44

45
### ServletWebServerFactoryConfiguration.EmbeddedTomcat
46

47
Configuration class specifically for embedded Tomcat web server factory creation.
48

49
```java { .api }
50
/**
51
 * Configuration for embedded Tomcat servlet web server factory
52
 */
53
@Configuration(proxyBeanMethods = false)
54
@ConditionalOnClass({ Servlet.class, Tomcat.class, UpgradeProtocol.class })
55
@ConditionalOnMissingBean(value = ServletWebServerFactory.class, 
56
                          search = SearchStrategy.CURRENT)
57
static class EmbeddedTomcat {
58
    
59
    /** Creates Tomcat servlet web server factory bean */
60
    @Bean
61
    TomcatServletWebServerFactory tomcatServletWebServerFactory(
62
            ObjectProvider<TomcatConnectorCustomizer> connectorCustomizers,
63
            ObjectProvider<TomcatContextCustomizer> contextCustomizers,
64
            ObjectProvider<TomcatProtocolHandlerCustomizer<?>> protocolHandlerCustomizers) {
65
        
66
        TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory();
67
        
68
        // Apply all discovered customizers
69
        factory.getTomcatConnectorCustomizers()
70
               .addAll(connectorCustomizers.orderedStream().collect(Collectors.toList()));
71
        factory.getTomcatContextCustomizers()
72
               .addAll(contextCustomizers.orderedStream().collect(Collectors.toList()));
73
        factory.getTomcatProtocolHandlerCustomizers()
74
               .addAll(protocolHandlerCustomizers.orderedStream().collect(Collectors.toList()));
75
        
76
        return factory;
77
    }
78
}
79
```
80

81
### TomcatServletWebServerFactoryCustomizer
82

83
Applies `ServerProperties` configuration to Tomcat servlet web server factories.
84

85
```java { .api }
86
/**
87
 * Customizer that applies ServerProperties to Tomcat servlet web server factories
88
 */
89
public class TomcatServletWebServerFactoryCustomizer
90
        implements WebServerFactoryCustomizer<TomcatServletWebServerFactory>, Ordered {
91
    
92
    /** Constructor with server properties */
93
    public TomcatServletWebServerFactoryCustomizer(ServerProperties serverProperties);
94
    
95
    /** Applies Tomcat-specific configuration from properties */
96
    @Override
97
    public void customize(TomcatServletWebServerFactory factory) {
98
        ServerProperties.Tomcat tomcatProperties = serverProperties.getTomcat();
99
        
100
        // Apply TLD skip patterns
101
        if (!tomcatProperties.getAdditionalTldSkipPatterns().isEmpty()) {
102
            factory.addTldSkipPatterns(tomcatProperties.getAdditionalTldSkipPatterns()
103
                                      .toArray(new String[0]));
104
        }
105
        
106
        // Apply context root redirect setting
107
        if (tomcatProperties.getRedirectContextRoot() != null) {
108
            customizeRedirectContextRoot(factory, tomcatProperties.getRedirectContextRoot());
109
        }
110
        
111
        // Apply relative redirects setting
112
        customizeUseRelativeRedirects(factory, tomcatProperties.getUseRelativeRedirects());
113
        
114
        // Apply MBean registry setting
115
        customizeDisableMBeanRegistry(factory, tomcatProperties.getMbeanregistry());
116
    }
117
    
118
    /** Returns execution order for this customizer */
119
    @Override
120
    public int getOrder();
121
}
122
```
123

124
### TomcatWebServerFactoryCustomizer
125

126
Applies common Tomcat configuration for both servlet and reactive web server factories.
127

128
```java { .api }
129
/**
130
 * Customizer that applies common Tomcat configuration to web server factories
131
 */
132
public class TomcatWebServerFactoryCustomizer
133
        implements WebServerFactoryCustomizer<ConfigurableTomcatWebServerFactory>, Ordered {
134
    
135
    /** Constructor with server properties */
136
    public TomcatWebServerFactoryCustomizer(ServerProperties serverProperties);
137
    
138
    /** Applies common Tomcat configuration from properties */
139
    @Override
140
    public void customize(ConfigurableTomcatWebServerFactory factory) {
141
        ServerProperties.Tomcat tomcatProperties = serverProperties.getTomcat();
142
        
143
        // Base directory configuration
144
        if (tomcatProperties.getBasedir() != null) {
145
            factory.setBaseDirectory(tomcatProperties.getBasedir());
146
        }
147
        
148
        // Background processor delay
149
        if (tomcatProperties.getBackgroundProcessorDelay() != null) {
150
            factory.setBackgroundProcessorDelay(
151
                (int) tomcatProperties.getBackgroundProcessorDelay().getSeconds());
152
        }
153
        
154
        // URI encoding
155
        if (tomcatProperties.getUriEncoding() != null) {
156
            factory.setUriEncoding(tomcatProperties.getUriEncoding());
157
        }
158
        
159
        // Apply connector customizations
160
        customizeConnector(factory, tomcatProperties);
161
        
162
        // Apply static resource settings
163
        customizeStaticResources(factory, tomcatProperties.getResource());
164
        
165
        // Apply remote IP configuration
166
        customizeRemoteIpValve(factory, tomcatProperties.getRemoteip());
167
    }
168
    
169
    /** Returns execution order for this customizer */
170
    @Override
171
    public int getOrder();
172
}
173
```
174

175
### ReactiveWebServerFactoryAutoConfiguration
176

177
Auto-configuration for reactive web servers, including Tomcat reactive support.
178

179
```java { .api }
180
/**
181
 * Auto-configuration for reactive web server factories
182
 */
183
@AutoConfiguration
184
@ConditionalOnClass(HttpHandler.class)
185
@ConditionalOnWebApplication(type = WebApplicationType.REACTIVE)
186
@EnableConfigurationProperties(ServerProperties.class)
187
@Import({ ReactiveWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar.class,
188
         ReactiveWebServerFactoryConfiguration.EmbeddedTomcat.class,
189
         ReactiveWebServerFactoryConfiguration.EmbeddedJetty.class,
190
         ReactiveWebServerFactoryConfiguration.EmbeddedUndertow.class,
191
         ReactiveWebServerFactoryConfiguration.EmbeddedNetty.class })
192
public class ReactiveWebServerFactoryAutoConfiguration {
193
    
194
    /** Creates reactive web server factory customizer */
195
    @Bean
196
    public ReactiveWebServerFactoryCustomizer reactiveWebServerFactoryCustomizer(
197
            ServerProperties serverProperties);
198
}
199
```
200

201
### ReactiveWebServerFactoryConfiguration.EmbeddedTomcat
202

203
Configuration class for embedded Tomcat reactive web server factory.
204

205
```java { .api }
206
/**
207
 * Configuration for embedded Tomcat reactive web server factory  
208
 */
209
@Configuration(proxyBeanMethods = false)
210
@ConditionalOnClass({ Tomcat.class })
211
@ConditionalOnMissingBean(value = ReactiveWebServerFactory.class,
212
                          search = SearchStrategy.CURRENT)
213
static class EmbeddedTomcat {
214
    
215
    /** Creates Tomcat reactive web server factory bean */
216
    @Bean
217
    TomcatReactiveWebServerFactory tomcatReactiveWebServerFactory(
218
            ObjectProvider<TomcatConnectorCustomizer> connectorCustomizers,
219
            ObjectProvider<TomcatContextCustomizer> contextCustomizers,
220
            ObjectProvider<TomcatProtocolHandlerCustomizer<?>> protocolHandlerCustomizers) {
221
        
222
        TomcatReactiveWebServerFactory factory = new TomcatReactiveWebServerFactory();
223
        
224
        // Apply customizers
225
        factory.getTomcatConnectorCustomizers()
226
               .addAll(connectorCustomizers.orderedStream().collect(Collectors.toList()));
227
        factory.getTomcatContextCustomizers()
228
               .addAll(contextCustomizers.orderedStream().collect(Collectors.toList()));
229
        factory.getTomcatProtocolHandlerCustomizers()
230
               .addAll(protocolHandlerCustomizers.orderedStream().collect(Collectors.toList()));
231
        
232
        return factory;
233
    }
234
}
235
```
236

237
### TomcatReactiveWebServerFactoryCustomizer
238

239
Applies configuration to Tomcat reactive web server factories.
240

241
```java { .api }
242
/**
243
 * Customizer for Tomcat reactive web server factories
244
 */
245
public class TomcatReactiveWebServerFactoryCustomizer
246
        implements WebServerFactoryCustomizer<TomcatReactiveWebServerFactory>, Ordered {
247
    
248
    /** Constructor with server properties */
249
    public TomcatReactiveWebServerFactoryCustomizer(ServerProperties serverProperties);
250
    
251
    /** Applies Tomcat reactive-specific configuration */
252
    @Override
253
    public void customize(TomcatReactiveWebServerFactory factory);
254
    
255
    /** Returns execution order for this customizer */
256
    @Override
257
    public int getOrder();
258
}
259
```
260

261
## WebSocket Auto-Configuration
262

263
### TomcatWebSocketServletWebServerCustomizer
264

265
Customizes Tomcat for WebSocket support in servlet environments.
266

267
```java { .api }
268
/**
269
 * Customizer for Tomcat WebSocket support in servlet environments
270
 */
271
@Configuration(proxyBeanMethods = false)
272
@ConditionalOnClass({ Tomcat.class, WsSci.class })
273
static class TomcatWebSocketConfiguration {
274
    
275
    /** Creates WebSocket servlet web server customizer */
276
    @Bean
277
    @ConditionalOnMissingBean(name = "tomcatWebSocketServletWebServerCustomizer")
278
    TomcatWebSocketServletWebServerCustomizer tomcatWebSocketServletWebServerCustomizer() {
279
        return new TomcatWebSocketServletWebServerCustomizer();
280
    }
281
}
282
```
283

284
### TomcatWebSocketReactiveWebServerCustomizer
285

286
Customizes Tomcat for WebSocket support in reactive environments.
287

288
```java { .api }
289
/**
290
 * Customizer for Tomcat WebSocket support in reactive environments
291
 */
292
@Configuration(proxyBeanMethods = false)
293
@ConditionalOnClass({ Tomcat.class, WsSci.class })
294
static class TomcatWebSocketReactiveConfiguration {
295
    
296
    /** Creates WebSocket reactive web server customizer */
297
    @Bean
298
    @ConditionalOnMissingBean(name = "tomcatWebSocketReactiveWebServerCustomizer")
299
    TomcatWebSocketReactiveWebServerCustomizer tomcatWebSocketReactiveWebServerCustomizer() {
300
        return new TomcatWebSocketReactiveWebServerCustomizer();
301
    }
302
}
303
```
304

305
## Metrics Auto-Configuration
306

307
### TomcatMetricsAutoConfiguration
308

309
Auto-configuration for Tomcat metrics collection through Micrometer.
310

311
```java { .api }
312
/**
313
 * Auto-configuration for Tomcat metrics collection
314
 */
315
@AutoConfiguration(after = { MetricsAutoConfiguration.class,
316
                           CompositeMeterRegistryAutoConfiguration.class })
317
@ConditionalOnClass({ Tomcat.class, MeterRegistry.class })
318
@ConditionalOnBean(MeterRegistry.class)
319
@ConditionalOnProperty(value = "management.metrics.web.server.request.autotime.enabled",
320
                      matchIfMissing = true)
321
@EnableConfigurationProperties(MetricsProperties.class)
322
public class TomcatMetricsAutoConfiguration {
323
    
324
    /** Creates Tomcat metrics binder */
325
    @Bean
326
    @ConditionalOnMissingBean
327
    public TomcatMetricsBinder tomcatMetricsBinder(MeterRegistry meterRegistry) {
328
        return new TomcatMetricsBinder(meterRegistry);
329
    }
330
    
331
    /** Creates Tomcat metrics web server factory customizer */
332
    @Bean
333
    @ConditionalOnMissingBean
334
    public TomcatMetricsWebServerFactoryCustomizer tomcatMetricsCustomizer(
335
            MeterRegistry meterRegistry, MetricsProperties metricsProperties) {
336
        return new TomcatMetricsWebServerFactoryCustomizer(meterRegistry, metricsProperties);
337
    }
338
}
339
```
340

341
## Conditional Configuration
342

343
Auto-configuration uses Spring Boot's conditional annotations to ensure proper component setup:
344

345
### Class Presence Conditions
346

347
```java
348
@ConditionalOnClass({ Servlet.class, Tomcat.class, UpgradeProtocol.class })
349
// Only activate when Tomcat classes are available
350

351
@ConditionalOnClass(name = "org.apache.catalina.startup.Tomcat")  
352
// Check for specific Tomcat class by name
353
```
354

355
### Bean Existence Conditions
356

357
```java
358
@ConditionalOnMissingBean(value = ServletWebServerFactory.class)
359
// Only create if no other web server factory exists
360

361
@ConditionalOnBean(MeterRegistry.class)
362
// Only create if MeterRegistry bean exists
363
```
364

365
### Property Conditions
366

367
```java
368
@ConditionalOnProperty(value = "server.forward-headers-strategy", 
369
                      havingValue = "framework")
370
// Only activate when specific property value is set
371

372
@ConditionalOnProperty(value = "management.metrics.web.server.request.autotime.enabled",
373
                      matchIfMissing = true)
374
// Activate by default unless explicitly disabled
375
```
376

377
### Web Application Type Conditions
378

379
```java
380
@ConditionalOnWebApplication(type = WebApplicationType.SERVLET)
381
// Only for servlet web applications
382

383
@ConditionalOnWebApplication(type = WebApplicationType.REACTIVE)  
384
// Only for reactive web applications
385
```
386

387
## Configuration Processing Order
388

389
Auto-configuration components are processed in a specific order:
390

391
1. **Core Auto-Configuration**: `ServletWebServerFactoryAutoConfiguration` or `ReactiveWebServerFactoryAutoConfiguration`
392
2. **Factory Creation**: Tomcat web server factory beans are created
393
3. **Built-in Customizers**: Framework-provided customizers are applied
394
4. **Property Customizers**: Properties-based customizers apply configuration
395
5. **User Customizers**: Application-defined customizer beans are discovered and applied
396
6. **Final Validation**: Configuration is validated and server is prepared for startup
397

398
This ordering ensures that user customizations can override framework defaults while maintaining proper initialization sequence.