0
# Spring Boot Starter Jetty
1

2
Spring Boot Starter Jetty provides Eclipse Jetty as an embedded servlet container for Spring Boot applications. It serves as a drop-in replacement for the default Tomcat container, offering advanced WebSocket support, custom server configurations, and specific performance characteristics that Jetty provides over other embedded containers.
3

4
## Package Information
5

6
- **Package Name**: spring-boot-starter-jetty
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven dependencies or replace `spring-boot-starter-web` with `spring-boot-starter-jetty`
10

11
```xml
12
<dependency>
13
    <groupId>org.springframework.boot</groupId>
14
    <artifactId>spring-boot-starter-jetty</artifactId>
15
</dependency>
16
```
17

18
For Gradle:
19
```groovy
20
implementation 'org.springframework.boot:spring-boot-starter-jetty'
21
```
22

23
## Core Imports
24

25
```java { .api }
26
import org.springframework.boot.web.embedded.jetty.JettyServletWebServerFactory;
27
import org.springframework.boot.web.embedded.jetty.JettyReactiveWebServerFactory;
28
import org.springframework.boot.web.embedded.jetty.JettyServerCustomizer;
29
import org.springframework.boot.web.embedded.jetty.ConfigurableJettyWebServerFactory;
30
```
31

32
## Basic Usage
33

34
### Replacing Tomcat with Jetty
35

36
```java
37
// In your main application or configuration class
38
@SpringBootApplication
39
public class JettyApplication {
40
    public static void main(String[] args) {
41
        SpringApplication.run(JettyApplication.class, args);
42
    }
43
}
44
```
45

46
```xml
47
<!-- Exclude Tomcat and include Jetty -->
48
<dependency>
49
    <groupId>org.springframework.boot</groupId>
50
    <artifactId>spring-boot-starter-web</artifactId>
51
    <exclusions>
52
        <exclusion>
53
            <groupId>org.springframework.boot</groupId>
54
            <artifactId>spring-boot-starter-tomcat</artifactId>
55
        </exclusion>
56
    </exclusions>
57
</dependency>
58
<dependency>
59
    <groupId>org.springframework.boot</groupId>
60
    <artifactId>spring-boot-starter-jetty</artifactId>
61
</dependency>
62
```
63

64
### Custom Jetty Configuration
65

66
```java
67
@Configuration
68
public class JettyConfig {
69
    
70
    @Bean
71
    public JettyServletWebServerFactory jettyWebServerFactory() {
72
        JettyServletWebServerFactory factory = new JettyServletWebServerFactory();
73
        factory.setPort(8080);
74
        factory.addServerCustomizers(new JettyServerCustomizer() {
75
            @Override
76
            public void customize(Server server) {
77
                // Custom server configuration
78
            }
79
        });
80
        return factory;
81
    }
82
}
83
```
84

85
## Architecture
86

87
Spring Boot Starter Jetty integrates with Spring Boot's auto-configuration system through several key components:
88

89
- **Web Server Factories**: Create and configure Jetty server instances for both servlet and reactive applications
90
- **Auto-Configuration**: Automatic detection and configuration based on classpath presence
91
- **Customizers**: Extension points for modifying server behavior and configuration
92
- **Properties Support**: Integration with Spring Boot's externalized configuration system
93
- **Actuator Integration**: Built-in metrics and monitoring support for Jetty servers
94

95
## Capabilities
96

97
### Servlet Web Server
98

99
Core servlet container functionality using Jetty as the embedded server. Provides complete servlet container capabilities with Spring Boot integration.
100

101
```java { .api }
102
public class JettyServletWebServerFactory 
103
    extends AbstractServletWebServerFactory 
104
    implements ConfigurableJettyWebServerFactory, ResourceLoaderAware {
105
    
106
    public JettyServletWebServerFactory();
107
    public JettyServletWebServerFactory(int port);
108
    public JettyServletWebServerFactory(String contextPath, int port);
109
    
110
    public WebServer getWebServer(ServletContextInitializer... initializers);
111
    public void addServerCustomizers(JettyServerCustomizer... customizers);
112
    public void setMaxConnections(int maxConnections);
113
    public void setResourceLoader(ResourceLoader resourceLoader);
114
    public Collection<JettyServerCustomizer> getServerCustomizers();
115
}
116
```
117

118
[Servlet Web Server](./servlet-web-server.md)
119

120
### Reactive Web Server
121

122
Reactive web server implementation using Jetty for WebFlux applications. Provides non-blocking, reactive HTTP server capabilities.
123

124
```java { .api }
125
public class JettyReactiveWebServerFactory 
126
    extends AbstractReactiveWebServerFactory 
127
    implements ConfigurableJettyWebServerFactory {
128
    
129
    public JettyReactiveWebServerFactory();
130
    public JettyReactiveWebServerFactory(int port);
131
    
132
    public WebServer getWebServer(HttpHandler httpHandler);
133
    public void addServerCustomizers(JettyServerCustomizer... customizers);
134
    public void setMaxConnections(int maxConnections);
135
    public void setResourceFactory(JettyResourceFactory resourceFactory);
136
    public Collection<JettyServerCustomizer> getServerCustomizers();
137
}
138
```
139

140
[Reactive Web Server](./reactive-web-server.md)
141

142
### Server Configuration
143

144
Comprehensive server configuration and customization options including SSL, threading, connectors, and advanced Jetty features.
145

146
```java { .api }
147
public interface JettyServerCustomizer {
148
    void customize(Server server);
149
}
150

151
public interface ConfigurableJettyWebServerFactory extends ConfigurableWebServerFactory {
152
    void addServerCustomizers(JettyServerCustomizer... customizers);
153
    void setUseForwardHeaders(boolean useForwardHeaders);
154
    void setAcceptors(int acceptors);
155
    void setSelectors(int selectors);
156
    void setMaxConnections(int maxConnections);
157
    void setThreadPool(ThreadPool threadPool);
158
}
159
```
160

161
[Server Configuration](./server-configuration.md)
162

163
### WebSocket Support
164

165
WebSocket capabilities for both servlet and reactive applications with Jakarta WebSocket API support.
166

167
```java { .api }
168
public class JettyWebSocketServletWebServerCustomizer implements WebServerFactoryCustomizer<JettyServletWebServerFactory> {
169
    public void customize(JettyServletWebServerFactory factory);
170
}
171

172
public class JettyWebSocketReactiveWebServerCustomizer implements WebServerFactoryCustomizer<JettyReactiveWebServerFactory> {
173
    public void customize(JettyReactiveWebServerFactory factory);
174
}
175
```
176

177
[WebSocket Support](./websocket-support.md)
178

179
### HTTP Client
180

181
HTTP client builders for creating Jetty-based HTTP clients in Spring Boot applications.
182

183
```java { .api }
184
public class JettyClientHttpRequestFactoryBuilder 
185
    implements ClientHttpRequestFactoryBuilder<JettyClientHttpRequestFactory> {
186
    
187
    public JettyClientHttpRequestFactoryBuilder();
188
    public JettyClientHttpRequestFactoryBuilder httpClient(HttpClient httpClient);
189
    public JettyClientHttpRequestFactoryBuilder connectTimeout(Duration connectTimeout);
190
    public JettyClientHttpRequestFactoryBuilder readTimeout(Duration readTimeout);
191
    public JettyClientHttpRequestFactory build();
192
}
193

194
public class JettyHttpClientBuilder {
195
    public JettyHttpClientBuilder();
196
    public JettyHttpClientBuilder sslContextFactory(SslContextFactory.Client sslContextFactory);
197
    public JettyHttpClientBuilder connectTimeout(Duration connectTimeout);
198
    public JettyHttpClientBuilder idleTimeout(Duration idleTimeout);
199
    public HttpClient build();
200
}
201
```
202

203
[HTTP Client](./http-client.md)
204

205
### Auto-Configuration
206

207
Spring Boot auto-configuration classes that automatically configure Jetty based on application properties and classpath detection.
208

209
```java { .api }
210
public class JettyWebServerFactoryCustomizer 
211
    implements WebServerFactoryCustomizer<ConfigurableJettyWebServerFactory> {
212
    
213
    public JettyWebServerFactoryCustomizer(ServerProperties serverProperties, 
214
                                         ObjectProvider<JettyThreadPool> threadPool);
215
    public void customize(ConfigurableJettyWebServerFactory factory);
216
}
217

218
public class JettyVirtualThreadsWebServerFactoryCustomizer 
219
    implements WebServerFactoryCustomizer<ConfigurableJettyWebServerFactory> {
220
    
221
    public JettyVirtualThreadsWebServerFactoryCustomizer();
222
    public void customize(ConfigurableJettyWebServerFactory factory);
223
}
224

225
public class JettyThreadPool implements ThreadPool {
226
    public static JettyThreadPool create(ServerProperties.Jetty jettyProperties);
227
    public JettyThreadPool();
228
    public JettyThreadPool(int maxThreads, int minThreads, int idleTimeout);
229
    public void setMaxThreads(int maxThreads);
230
    public void setMinThreads(int minThreads);
231
    public void setIdleTimeout(int idleTimeout);
232
    public void execute(Runnable job);
233
    public boolean isLowOnThreads();
234
}
235
```
236

237
## Types
238

239
### Core Server Types
240

241
```java { .api }
242
public class JettyWebServer implements WebServer {
243
    public JettyWebServer(Server server);
244
    public JettyWebServer(Server server, boolean autoStart);
245
    public void start() throws WebServerException;
246
    public void stop() throws WebServerException;
247
    public int getPort();
248
    public Server getServer();
249
    public void shutDownGracefully(GracefulShutdownCallback callback);
250
    public void destroy();
251
}
252

253
public class JettyEmbeddedWebAppContext extends WebAppContext {
254
    public JettyEmbeddedWebAppContext();
255
    public JettyEmbeddedWebAppContext(String webApp, String contextPath);
256
    public void setTempDirectory(File tempDirectory);
257
    public void setParentLoaderPriority(boolean parentLoaderPriority);
258
    public void setSessionTimeout(int sessionTimeout);
259
}
260

261
public class JettyEmbeddedErrorHandler extends ErrorHandler {
262
    public JettyEmbeddedErrorHandler();
263
    public void handle(String target, Request baseRequest, 
264
                      HttpServletRequest request, HttpServletResponse response);
265
    public void setShowServlet(boolean showServlet);
266
    public void setShowStacks(boolean showStacks);
267
}
268

269
public class GracefulShutdown {
270
    public GracefulShutdown();
271
    public void shutDownGracefully(GracefulShutdownCallback callback);
272
    public void setTimeout(Duration timeout);
273
}
274
```
275

276
### Resource Management Types
277

278
```java { .api }
279
public class JettyResourceFactory implements DisposableBean, InitializingBean {
280
    public JettyResourceFactory();
281
    public HttpClient getHttpClient();
282
    public Executor getExecutor();
283
    public Scheduler getScheduler();
284
    public ByteBufferPool getByteBufferPool();
285
    public void setThreadPool(ThreadPool threadPool);
286
    public void setExecutor(Executor executor);
287
    public void setScheduler(Scheduler scheduler);
288
    public void setByteBufferPool(ByteBufferPool byteBufferPool);
289
    public void afterPropertiesSet() throws Exception;
290
    public void destroy() throws Exception;
291
}
292
```
293

294
### Customizer Types
295

296
```java { .api }
297
public class SslServerCustomizer implements JettyServerCustomizer {
298
    public SslServerCustomizer();
299
    public void customize(Server server);
300
    public void configureSslContextFactory(SslContextFactory.Server sslContextFactory);
301
    public void setIncludeProtocols(String... protocols);
302
    public void setIncludeCipherSuites(String... cipherSuites);
303
    public void setNeedClientAuth(boolean needClientAuth);
304
    public void setWantClientAuth(boolean wantClientAuth);
305
}
306

307
public class ForwardHeadersCustomizer implements JettyServerCustomizer {
308
    public ForwardHeadersCustomizer();
309
    public void customize(Server server);
310
    public void setTrustedProxies(String... trustedProxies);
311
    public void setForwardedHostHeader(String forwardedHostHeader);
312
    public void setForwardedPortHeader(String forwardedPortHeader);
313
    public void setForwardedProtoHeader(String forwardedProtoHeader);
314
}
315
```
316

317
### Configuration Properties
318

319
Jetty-specific configuration properties available through Spring Boot's `server.jetty.*` namespace:
320

321
```yaml
322
server:
323
  jetty:
324
    acceptors: 2                    # Number of acceptor threads
325
    selectors: 4                    # Number of selector threads  
326
    max-http-post-size: 10MB        # Maximum HTTP POST size
327
    threads:
328
      max: 200                      # Maximum thread pool size
329
      min: 10                       # Minimum thread pool size
330
      idle-timeout: 60s             # Thread idle timeout
331
    connection:
332
      idle-timeout: 30s             # Connection idle timeout
333
      accept-queue-size: 128        # Accept queue size
334
```