0
# Web Server Factories
1

2
Core factory classes for creating and configuring Tomcat-based web servers. These factories provide both servlet and reactive web server support with extensive customization options and integrate seamlessly with Spring Boot's auto-configuration system.
3

4
## Capabilities
5

6
### TomcatServletWebServerFactory
7

8
Main factory class for creating Tomcat-based servlet web servers. Extends `AbstractServletWebServerFactory` and implements `ConfigurableTomcatWebServerFactory`.
9

10
```java { .api }
11
/**
12
 * Factory for creating Tomcat-based servlet web servers
13
 */
14
public class TomcatServletWebServerFactory extends AbstractServletWebServerFactory 
15
    implements ConfigurableTomcatWebServerFactory {
16
    
17
    /** Default constructor using auto-detected port */
18
    public TomcatServletWebServerFactory();
19
    
20
    /** Constructor with specific port */
21
    public TomcatServletWebServerFactory(int port);
22
    
23
    /** Constructor with context path and port */
24
    public TomcatServletWebServerFactory(String contextPath, int port);
25
    
26
    /** Creates and configures the web server with servlet context initializers */
27
    public WebServer getWebServer(ServletContextInitializer... initializers);
28
    
29
    /** Sets the Tomcat base directory for temporary files */
30
    public void setBaseDirectory(File baseDirectory);
31
    
32
    /** Sets the Tomcat connector protocol (default: Http11NioProtocol) */
33
    public void setProtocol(String protocol);
34
    
35
    /** Sets URI encoding charset (default: UTF-8) */
36
    public void setUriEncoding(Charset uriEncoding);
37
    
38
    /** Controls whether to disable Tomcat's MBean registry */
39
    public void setDisableMBeanRegistry(boolean disableMBeanRegistry);
40
    
41
    /** Gets the current TLD skip patterns */
42
    public Set<String> getTldSkipPatterns();
43
    
44
    /** Sets TLD skip patterns for faster startup */
45
    public void setTldSkipPatterns(Collection<String> patterns);
46
    
47
    /** Adds additional TLD skip patterns */
48
    public void addTldSkipPatterns(String... patterns);
49
    
50
    /** Adds Tomcat Engine-level valves for request processing */
51
    public void addEngineValves(Valve... engineValves);
52
    
53
    /** Adds Tomcat Context-level valves for request processing */
54
    public void addContextValves(Valve... contextValves);
55
    
56
    /** Adds context lifecycle listeners for webapp lifecycle events */
57
    public void addContextLifecycleListeners(LifecycleListener... listeners);
58
    
59
    /** Adds connector customizers for fine-grained connector configuration */
60
    public void addConnectorCustomizers(TomcatConnectorCustomizer... customizers);
61
    
62
    /** Adds context customizers for webapp context configuration */
63
    public void addContextCustomizers(TomcatContextCustomizer... customizers);
64
    
65
    /** Adds protocol handler customizers for low-level protocol configuration */
66
    public void addProtocolHandlerCustomizers(TomcatProtocolHandlerCustomizer<?>... customizers);
67
    
68
    /** Adds additional Tomcat connectors to the server */
69
    public void addAdditionalTomcatConnectors(Connector... connectors);
70
}
71
```
72

73
**Usage Examples:**
74

75
```java
76
import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
77
import org.springframework.context.annotation.Bean;
78
import org.springframework.context.annotation.Configuration;
79
import java.io.File;
80
import java.nio.charset.StandardCharsets;
81

82
@Configuration
83
public class TomcatConfig {
84
    
85
    @Bean
86
    public TomcatServletWebServerFactory tomcatFactory() {
87
        TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory(8080);
88
        factory.setBaseDirectory(new File("/tmp/tomcat"));
89
        factory.setUriEncoding(StandardCharsets.UTF_8);
90
        factory.addTldSkipPatterns("custom-*.jar", "legacy-*.jar");
91
        return factory;
92
    }
93
}
94
```
95

96
### TomcatReactiveWebServerFactory
97

98
Factory for creating Tomcat-based reactive web servers. Extends `AbstractReactiveWebServerFactory` and implements `ConfigurableTomcatWebServerFactory`.
99

100
```java { .api }
101
/**
102
 * Factory for creating Tomcat-based reactive web servers
103
 */
104
public class TomcatReactiveWebServerFactory extends AbstractReactiveWebServerFactory 
105
    implements ConfigurableTomcatWebServerFactory {
106
    
107
    /** Default constructor using auto-detected port */
108
    public TomcatReactiveWebServerFactory();
109
    
110
    /** Constructor with specific port */
111
    public TomcatReactiveWebServerFactory(int port);
112
    
113
    /** Creates reactive web server with HTTP handler */
114
    public WebServer getWebServer(HttpHandler httpHandler);
115
    
116
    /** Sets the Tomcat base directory for temporary files */
117
    public void setBaseDirectory(File baseDirectory);
118
    
119
    /** Sets background processor delay for maintenance tasks */
120
    public void setBackgroundProcessorDelay(int delay);
121
    
122
    /** Sets URI encoding charset */
123
    public void setUriEncoding(Charset uriEncoding);
124
    
125
    /** Adds Tomcat Engine-level valves for request processing */
126
    public void addEngineValves(Valve... engineValves);
127
    
128
    /** Adds connector customizers for fine-grained connector configuration */
129
    public void addConnectorCustomizers(TomcatConnectorCustomizer... customizers);
130
    
131
    /** Adds context customizers for webapp context configuration */
132
    public void addContextCustomizers(TomcatContextCustomizer... customizers);
133
    
134
    /** Adds protocol handler customizers for low-level protocol configuration */
135
    public void addProtocolHandlerCustomizers(TomcatProtocolHandlerCustomizer<?>... customizers);
136
}
137
```
138

139
### TomcatWebServer
140

141
WebServer implementation that controls a Tomcat web server instance. Usually created via factory classes but can be used directly for advanced scenarios.
142

143
```java { .api }
144
/**
145
 * WebServer implementation that manages a Tomcat server instance
146
 */
147
public class TomcatWebServer implements WebServer {
148
    
149
    /** Constructor with Tomcat instance */
150
    public TomcatWebServer(Tomcat tomcat);
151
    
152
    /** Constructor with auto-start control */
153
    public TomcatWebServer(Tomcat tomcat, boolean autoStart);
154
    
155
    /** Full constructor with shutdown configuration */
156
    public TomcatWebServer(Tomcat tomcat, boolean autoStart, Shutdown shutdown);
157
    
158
    /** Starts the web server */
159
    public void start() throws WebServerException;
160
    
161
    /** Stops the web server */
162
    public void stop() throws WebServerException;
163
    
164
    /** Gets the port the server is running on */
165
    public int getPort();
166
    
167
    /** Initiates graceful shutdown with callback */
168
    public void shutDownGracefully(GracefulShutdownCallback callback);
169
}
170
```
171

172
### ConfigurableTomcatWebServerFactory
173

174
Common interface for Tomcat-specific web server factory configuration, implemented by both servlet and reactive factories.
175

176
```java { .api }
177
/**
178
 * Common configuration interface for Tomcat web server factories
179
 */
180
public interface ConfigurableTomcatWebServerFactory {
181
    
182
    /** Sets Tomcat base directory for temporary files and work directories */
183
    void setBaseDirectory(File baseDirectory);
184
    
185
    /** Sets background processor delay in seconds for maintenance tasks */
186
    void setBackgroundProcessorDelay(int delay);
187
    
188
    /** Adds Tomcat Engine-level valves for request processing */
189
    void addEngineValves(Valve... engineValves);
190
    
191
    /** Adds connector customizers for fine-grained connector configuration */
192
    void addConnectorCustomizers(TomcatConnectorCustomizer... customizers);
193
    
194
    /** Adds context customizers for webapp context configuration */
195
    void addContextCustomizers(TomcatContextCustomizer... customizers);
196
    
197
    /** Adds protocol handler customizers for low-level protocol configuration */
198
    void addProtocolHandlerCustomizers(TomcatProtocolHandlerCustomizer<?>... customizers);
199
    
200
    /** Sets URI encoding for request/response processing */
201
    void setUriEncoding(Charset uriEncoding);
202
}
203
```
204

205
**Advanced Usage Example:**
206

207
```java
208
@Configuration
209
public class AdvancedTomcatConfig {
210
    
211
    @Bean
212
    public ConfigurableTomcatWebServerFactory configurableTomcat() {
213
        TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory();
214
        
215
        // Configure base settings
216
        factory.setBaseDirectory(new File("/opt/tomcat-temp"));
217
        factory.setBackgroundProcessorDelay(5);
218
        factory.setUriEncoding(StandardCharsets.UTF_8);
219
        
220
        // Add custom valves
221
        factory.addEngineValves(new AccessLogValve());
222
        
223
        // Add customizers
224
        factory.addConnectorCustomizers(connector -> {
225
            connector.setPort(8443);
226
            connector.setSecure(true);
227
            connector.setScheme("https");
228
        });
229
        
230
        factory.addContextCustomizers(context -> {
231
            context.setSessionTimeout(30);
232
            context.setCookies(false);
233
        });
234
        
235
        return factory;
236
    }
237
}
238
```
239

240
## Factory Integration
241

242
Web server factories are automatically configured by Spring Boot's auto-configuration system:
243

244
1. **Auto-Detection**: Factories are conditionally created based on classpath presence of Tomcat classes
245
2. **Property Binding**: Configuration properties are automatically applied via customizers
246
3. **Customizer Discovery**: All `TomcatConnectorCustomizer`, `TomcatContextCustomizer`, and `TomcatProtocolHandlerCustomizer` beans are automatically applied
247
4. **Startup Integration**: Factories are invoked during Spring Boot application startup to create the embedded server
248

249
## Error Handling
250

251
Factories may throw these exceptions during server creation:
252

253
- `WebServerException` - General web server configuration or startup issues
254
- `PortInUseException` - When the configured port is already in use  
255
- `IllegalStateException` - Invalid factory configuration or state
256

257
```java { .api }
258
/**
259
 * Exception thrown when a web server cannot be started or configured
260
 */
261
public class WebServerException extends RuntimeException {
262
    public WebServerException(String message);
263
    public WebServerException(String message, Throwable cause);
264
}
265

266
/**
267
 * Exception thrown when the configured port is already in use
268
 */
269
public class PortInUseException extends WebServerException {
270
    public PortInUseException(int port);
271
    public PortInUseException(int port, Throwable cause);
272
}
273
```