0
# Server Configuration
1

2
Dropwizard's pluggable server factory system supports different deployment patterns with configurable connectors, thread pools, and server implementations.
3

4
## Capabilities
5

6
### ServerFactory Interface
7

8
Base interface for building Jetty servers with pluggable implementations supporting different deployment patterns.
9

10
```java { .api }
11
/**
12
 * A factory for building Server instances for Dropwizard applications.
13
 */
14
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type", defaultImpl = DefaultServerFactory.class)
15
public interface ServerFactory extends Discoverable {
16
    /**
17
     * Build a server for the given Dropwizard application.
18
     * @param environment the application's environment
19
     * @return a Server running the Dropwizard application
20
     */
21
    Server build(Environment environment);
22
    
23
    /**
24
     * Configures the given environment with settings defined in the factory.
25
     * @param environment the application's environment
26
     */
27
    void configure(Environment environment);
28
}
29
```
30

31
The `@JsonTypeInfo` annotation enables polymorphic JSON deserialization based on the "type" property in configuration.
32

33
### DefaultServerFactory
34

35
Multi-connector server factory supporting separate application and admin connectors on different ports. This is the default and recommended configuration for production deployments.
36

37
```java { .api }
38
/**
39
 * Default server factory with separate application and admin connectors.
40
 */
41
@JsonTypeName("default")
42
public class DefaultServerFactory extends AbstractServerFactory {
43
    /**
44
     * Returns the application connectors.
45
     * @return list of application connectors
46
     */
47
    @JsonProperty("applicationConnectors")
48
    public List<ConnectorFactory> getApplicationConnectors();
49
    
50
    /**
51
     * Sets the application connectors.
52
     * @param connectors the application connectors
53
     */
54
    @JsonProperty("applicationConnectors")
55
    public void setApplicationConnectors(List<ConnectorFactory> connectors);
56
    
57
    /**
58
     * Returns the admin connectors.
59
     * @return list of admin connectors
60
     */
61
    @JsonProperty("adminConnectors")
62
    public List<ConnectorFactory> getAdminConnectors();
63
    
64
    /**
65
     * Sets the admin connectors.
66
     * @param connectors the admin connectors
67
     */
68
    @JsonProperty("adminConnectors")
69
    public void setAdminConnectors(List<ConnectorFactory> connectors);
70
    
71
    /**
72
     * Returns the admin maximum threads.
73
     * @return admin max threads
74
     */
75
    @JsonProperty("adminMaxThreads")
76
    public int getAdminMaxThreads();
77
    
78
    /**
79
     * Sets the admin maximum threads.
80
     * @param threads the admin max threads
81
     */
82
    @JsonProperty("adminMaxThreads")
83
    public void setAdminMaxThreads(int threads);
84
    
85
    /**
86
     * Returns the admin minimum threads.
87
     * @return admin min threads
88
     */
89
    @JsonProperty("adminMinThreads")
90
    public int getAdminMinThreads();
91
    
92
    /**
93
     * Sets the admin minimum threads.
94
     * @param threads the admin min threads
95
     */
96
    @JsonProperty("adminMinThreads")
97
    public void setAdminMinThreads(int threads);
98
}
99
```
100

101
**Configuration Example:**
102

103
```yaml
104
server:
105
  type: default
106
  applicationConnectors:
107
    - type: http
108
      port: 8080
109
      bindHost: 0.0.0.0
110
    - type: https
111
      port: 8443
112
      keyStorePath: /path/to/keystore.jks
113
      keyStorePassword: password
114
  adminConnectors:
115
    - type: http
116
      port: 8081
117
      bindHost: 127.0.0.1
118
  adminMaxThreads: 64
119
  adminMinThreads: 1
120
  maxThreads: 1024
121
  minThreads: 8
122
```
123

124
### SimpleServerFactory
125

126
Single-connector server factory that combines application and admin interfaces on the same port and connector. Useful for development and simple deployments.
127

128
```java { .api }
129
/**
130
 * Simple server factory with a single connector for both application and admin.
131
 */
132
@JsonTypeName("simple")
133
public class SimpleServerFactory extends AbstractServerFactory {
134
    /**
135
     * Returns the connector configuration.
136
     * @return the connector factory
137
     */
138
    @JsonProperty("connector")
139
    public ConnectorFactory getConnector();
140
    
141
    /**
142
     * Sets the connector configuration.
143
     * @param factory the connector factory
144
     */
145
    @JsonProperty("connector")
146
    public void setConnector(ConnectorFactory factory);
147
    
148
    /**
149
     * Returns the application context path.
150
     * @return the application context path
151
     */
152
    @JsonProperty("applicationContextPath")
153
    public String getApplicationContextPath();
154
    
155
    /**
156
     * Sets the application context path.
157
     * @param contextPath the application context path
158
     */
159
    @JsonProperty("applicationContextPath")
160
    public void setApplicationContextPath(String contextPath);
161
    
162
    /**
163
     * Returns the admin context path.
164
     * @return the admin context path
165
     */
166
    @JsonProperty("adminContextPath")
167
    public String getAdminContextPath();
168
    
169
    /**
170
     * Sets the admin context path.
171
     * @param contextPath the admin context path
172
     */
173
    @JsonProperty("adminContextPath")
174
    public void setAdminContextPath(String contextPath);
175
}
176
```
177

178
**Configuration Example:**
179

180
```yaml
181
server:
182
  type: simple
183
  connector:
184
    type: http
185
    port: 9000
186
    bindHost: 0.0.0.0
187
  applicationContextPath: /api
188
  adminContextPath: /admin
189
  maxThreads: 1024
190
  minThreads: 8
191
```
192

193
**Usage Examples:**
194

195
With simple server configuration, your application and admin interfaces are available at:
196
- Application: `http://localhost:9000/api/`
197
- Admin: `http://localhost:9000/admin/`
198

199
### AbstractServerFactory
200

201
Base class providing common server configuration shared by both DefaultServerFactory and SimpleServerFactory.
202

203
```java { .api }
204
/**
205
 * Base server factory implementation with common configuration.
206
 */
207
public abstract class AbstractServerFactory implements ServerFactory {
208
    /**
209
     * Returns the maximum number of threads.
210
     * @return max threads
211
     */
212
    @JsonProperty("maxThreads")
213
    public int getMaxThreads();
214
    
215
    /**
216
     * Sets the maximum number of threads.
217
     * @param count the max threads
218
     */
219
    @JsonProperty("maxThreads") 
220
    public void setMaxThreads(int count);
221
    
222
    /**
223
     * Returns the minimum number of threads.
224
     * @return min threads
225
     */
226
    @JsonProperty("minThreads")
227
    public int getMinThreads();
228
    
229
    /**
230
     * Sets the minimum number of threads.
231
     * @param count the min threads
232
     */
233
    @JsonProperty("minThreads")
234
    public void setMinThreads(int count);
235
    
236
    /**
237
     * Returns the max queued requests.
238
     * @return max queued requests
239
     */
240
    @JsonProperty("maxQueuedRequests")
241
    public int getMaxQueuedRequests();
242
    
243
    /**
244
     * Sets the max queued requests.
245
     * @param maxQueuedRequests the max queued requests
246
     */
247
    @JsonProperty("maxQueuedRequests")
248
    public void setMaxQueuedRequests(int maxQueuedRequests);
249
    
250
    /**
251
     * Returns the idle thread timeout.
252
     * @return idle thread timeout duration
253
     */
254
    @JsonProperty("idleThreadTimeout")
255
    public Duration getIdleThreadTimeout();
256
    
257
    /**
258
     * Sets the idle thread timeout.
259
     * @param idleThreadTimeout the idle thread timeout
260
     */
261
    @JsonProperty("idleThreadTimeout")
262
    public void setIdleThreadTimeout(Duration idleThreadTimeout);
263
    
264
    /**
265
     * Returns whether detailed dump is enabled.
266
     * @return true if detailed dump is enabled
267
     */
268
    @JsonProperty("detailedJsonParseExceptionMessages")
269
    public boolean isDetailedJsonParseExceptionMessages();
270
    
271
    /**
272
     * Sets whether detailed dump is enabled.
273
     * @param detailed true to enable detailed messages
274
     */
275
    @JsonProperty("detailedJsonParseExceptionMessages")
276
    public void setDetailedJsonParseExceptionMessages(boolean detailed);
277
    
278
    /**
279
     * Returns the server push filter factory.
280
     * @return the server push filter factory (nullable)
281
     */
282
    @JsonProperty("serverPush")
283
    public ServerPushFilterFactory getServerPush();
284
    
285
    /**
286
     * Sets the server push filter factory.
287
     * @param serverPush the server push filter factory
288
     */
289
    @JsonProperty("serverPush")
290
    public void setServerPush(ServerPushFilterFactory serverPush);
291
    
292
    /**
293
     * Returns whether graceful shutdown is enabled.
294
     * @return true if graceful shutdown is enabled
295
     */
296
    @JsonProperty("shutdownGracePeriod")
297
    public Duration getShutdownGracePeriod();
298
    
299
    /**
300
     * Sets the graceful shutdown period.
301
     * @param shutdownGracePeriod the shutdown grace period
302
     */
303
    @JsonProperty("shutdownGracePeriod")
304
    public void setShutdownGracePeriod(Duration shutdownGracePeriod);
305
    
306
    /**
307
     * Returns whether to dump heap on OutOfMemoryError.
308
     * @return true if heap dump on OOM is enabled
309
     */
310
    @JsonProperty("dumpHeapOnOOM")
311
    public boolean isDumpHeapOnOOM();
312
    
313
    /**
314
     * Sets whether to dump heap on OutOfMemoryError.
315
     * @param dumpHeapOnOOM true to enable heap dump on OOM
316
     */
317
    @JsonProperty("dumpHeapOnOOM")
318
    public void setDumpHeapOnOOM(boolean dumpHeapOnOOM);
319
}
320
```
321

322
## Server Configuration Examples
323

324
### Production Configuration (Default Server Factory)
325

326
```yaml
327
server:
328
  type: default
329
  maxThreads: 1024
330
  minThreads: 8
331
  maxQueuedRequests: 1024
332
  idleThreadTimeout: 1 minute
333
  shutdownGracePeriod: 30 seconds
334
  
335
  applicationConnectors:
336
    - type: http
337
      port: 8080
338
      bindHost: 0.0.0.0
339
      idleTimeout: 30 seconds
340
      soLingerTime: -1s
341
      reuseAddress: true
342
      useServerHeader: false
343
      useDateHeader: false
344
      useForwardedHeaders: true
345
      
346
  adminConnectors:
347
    - type: http
348
      port: 8081
349
      bindHost: 127.0.0.1
350
      
351
  adminMaxThreads: 64
352
  adminMinThreads: 1
353
```
354

355
### Development Configuration (Simple Server Factory)
356

357
```yaml
358
server:
359
  type: simple
360
  applicationContextPath: /api
361
  adminContextPath: /admin
362
  connector:
363
    type: http
364
    port: 8080
365
    bindHost: localhost
366
  maxThreads: 100
367
  minThreads: 4
368
```
369

370
### HTTPS Configuration
371

372
```yaml
373
server:
374
  type: default
375
  applicationConnectors:
376
    - type: https
377
      port: 8443
378
      keyStorePath: /etc/ssl/dropwizard.jks
379
      keyStorePassword: changeit
380
      trustStorePath: /etc/ssl/dropwizard.jks
381
      trustStorePassword: changeit
382
      keyManagerPassword: changeit
383
      needClientAuth: false
384
      wantClientAuth: false
385
      certAlias: dropwizard
386
      crlPath: /etc/ssl/crl.pem
387
      enableCRLDP: false
388
      enableOCSP: false
389
      maxCertPathLength: -1
390
      ocspResponderUrl: http://winqa2003-ocsp.mlbcorp.net/ocsp
391
      jceProvider: BC
392
      validateCerts: true
393
      validatePeers: true
394
      supportedProtocols: [TLSv1.1, TLSv1.2]
395
      excludedProtocols: []
396
      supportedCipherSuites: []
397
      excludedCipherSuites: []
398
      allowRenegotiation: true
399
      endpointIdentificationAlgorithm: HTTPS
400
      
401
  adminConnectors:
402
    - type: http
403
      port: 8081
404
      bindHost: 127.0.0.1
405
```
406

407
## Custom Server Factory
408

409
You can create custom server factories by implementing the ServerFactory interface:
410

411
```java
412
@JsonTypeName("custom")
413
public class CustomServerFactory implements ServerFactory {
414
    @Override
415
    public Server build(Environment environment) {
416
        // Build custom Jetty server
417
        final QueuedThreadPool threadPool = new QueuedThreadPool();
418
        threadPool.setMinThreads(8);
419
        threadPool.setMaxThreads(512);
420
        
421
        final Server server = new Server(threadPool);
422
        
423
        // Add custom connectors and handlers
424
        // ...
425
        
426
        return server;
427
    }
428
    
429
    @Override
430
    public void configure(Environment environment) {
431
        // Configure environment with custom settings
432
    }
433
}
434

435
// Register in your application
436
@Override
437
public void initialize(Bootstrap<MyConfiguration> bootstrap) {
438
    // Register custom server factory for JSON type resolution
439
    bootstrap.getObjectMapper().getSubtypeResolver()
440
        .registerSubtypes(CustomServerFactory.class);
441
}
442
```
443

444
## Types
445

446
```java { .api }
447
// Jetty Server and related types
448
public class Server {
449
    public void start() throws Exception;
450
    public void stop() throws Exception;
451
    public void join() throws InterruptedException;
452
}
453

454
// Connector factories for different protocols
455
public interface ConnectorFactory {
456
    Connector build(Server server, MetricRegistry metrics, String name, ThreadPool threadPool);
457
}
458

459
public class HttpConnectorFactory implements ConnectorFactory {
460
    // HTTP connector configuration
461
}
462

463
public class HttpsConnectorFactory extends HttpConnectorFactory {
464
    // HTTPS connector configuration  
465
}
466

467
// Thread pool configuration
468
public class QueuedThreadPool extends AbstractLifeCycle implements ThreadPool {
469
    public void setMinThreads(int minThreads);
470
    public void setMaxThreads(int maxThreads);
471
    public void setIdleTimeout(int idleTimeout);
472
}
473

474
// Duration for timeouts and intervals
475
public class Duration {
476
    public static Duration minutes(long minutes);
477
    public static Duration seconds(long seconds);
478
    public static Duration milliseconds(long milliseconds);
479
}
480
```