0
# Environment and Setup
1

2
The Environment and Bootstrap classes provide the runtime context and pre-start setup for Dropwizard applications, offering access to Jersey, servlet container, admin interface, lifecycle management, and health checks.
3

4
## Capabilities
5

6
### Environment Class
7

8
The runtime environment providing unified access to all application subsystems including Jersey, servlets, admin interface, lifecycle management, and health checks.
9

10
```java { .api }
11
/**
12
 * A Dropwizard application's environment.
13
 */
14
public class Environment {
15
    /**
16
     * Creates a new environment.
17
     * @param name the application name
18
     * @param objectMapper the ObjectMapper for the application
19
     * @param validatorFactory the validator factory
20
     * @param metricRegistry the metric registry
21
     * @param classLoader the class loader (nullable)
22
     * @param healthCheckRegistry the health check registry
23
     * @param configuration the application configuration
24
     */
25
    public Environment(String name,
26
                      ObjectMapper objectMapper,
27
                      ValidatorFactory validatorFactory,
28
                      MetricRegistry metricRegistry,
29
                      ClassLoader classLoader,
30
                      HealthCheckRegistry healthCheckRegistry,
31
                      Configuration configuration);
32
    
33
    /**
34
     * Convenience constructor for tests.
35
     * @param name the application name
36
     */
37
    public Environment(String name);
38
    
39
    /**
40
     * Returns the application's JerseyEnvironment.
41
     * @return the Jersey environment for JAX-RS configuration
42
     */
43
    public JerseyEnvironment jersey();
44
    
45
    /**
46
     * Returns the application's ServletEnvironment.
47
     * @return the servlet environment for servlet registration
48
     */
49
    public ServletEnvironment servlets();
50
    
51
    /**
52
     * Returns the application's AdminEnvironment.
53
     * @return the admin environment for admin interface
54
     */
55
    public AdminEnvironment admin();
56
    
57
    /**
58
     * Returns the application's LifecycleEnvironment.
59
     * @return the lifecycle environment for managed objects
60
     */
61
    public LifecycleEnvironment lifecycle();
62
    
63
    /**
64
     * Returns the application's HealthEnvironment.
65
     * @return the health environment for health checks
66
     */
67
    public HealthEnvironment health();
68
    
69
    /**
70
     * Returns the application's name.
71
     * @return the application name
72
     */
73
    public String getName();
74
    
75
    /**
76
     * Returns the application's ObjectMapper.
77
     * @return the JSON object mapper
78
     */
79
    public ObjectMapper getObjectMapper();
80
    
81
    /**
82
     * Returns the application's Validator.
83
     * @return the bean validator
84
     */
85
    public Validator getValidator();
86
    
87
    /**
88
     * Sets the application's Validator.
89
     * @param validator the bean validator
90
     */
91
    public void setValidator(Validator validator);
92
    
93
    /**
94
     * Returns the application's MetricRegistry.
95
     * @return the metrics registry
96
     */
97
    public MetricRegistry metrics();
98
    
99
    /**
100
     * Returns the application's HealthCheckRegistry.
101
     * @return the health check registry
102
     */
103
    public HealthCheckRegistry healthChecks();
104
    
105
    /**
106
     * Returns an ExecutorService to run time bound health checks.
107
     * @return the health check executor service
108
     */
109
    public ExecutorService getHealthCheckExecutorService();
110
    
111
    // Internal accessors
112
    public MutableServletContextHandler getApplicationContext();
113
    public Servlet getJerseyServletContainer();
114
    public MutableServletContextHandler getAdminContext();
115
}
116
```
117

118
**Usage Examples:**
119

120
```java
121
@Override
122
public void run(MyConfiguration configuration, Environment environment) {
123
    // Register JAX-RS resources
124
    environment.jersey().register(new UserResource(userService));
125
    environment.jersey().register(new OrderResource(orderService));
126
    
127
    // Register servlets
128
    environment.servlets().addServlet("metrics", new AdminServlet())
129
        .addMapping("/admin/metrics/*");
130
    
131
    // Register health checks
132
    environment.healthChecks().register("database", 
133
        new DatabaseHealthCheck(configuration.getDatabaseUrl()));
134
    environment.healthChecks().register("redis", 
135
        new RedisHealthCheck(configuration.getRedis()));
136
    
137
    // Register managed objects (lifecycle)
138
    environment.lifecycle().manage(new DatabaseManager(configuration));
139
    
140
    // Register admin tasks
141
    environment.admin().addTask(new CacheFlushTask(cacheService));
142
    
143
    // Access metrics
144
    final Timer requestTimer = environment.metrics().timer("requests");
145
    final Counter errorCounter = environment.metrics().counter("errors");
146
}
147
```
148

149
### Bootstrap Class
150

151
The pre-start application environment containing everything required to bootstrap a Dropwizard command. Used during application initialization to register bundles, commands, and configure core services.
152

153
```java { .api }
154
/**
155
 * The pre-start application environment for bootstrapping.
156
 * @param <T> the configuration type
157
 */
158
public class Bootstrap<T extends Configuration> {
159
    /**
160
     * Creates a new Bootstrap for the given application.
161
     * @param application a Dropwizard Application
162
     */
163
    public Bootstrap(Application<T> application);
164
    
165
    /**
166
     * Returns the bootstrap's Application.
167
     * @return the application instance
168
     */
169
    public Application<T> getApplication();
170
    
171
    /**
172
     * Adds the given bundle to the bootstrap.
173
     * @param bundle a ConfiguredBundle
174
     */
175
    public void addBundle(ConfiguredBundle<? super T> bundle);
176
    
177
    /**
178
     * Adds the given command to the bootstrap.
179
     * @param command a Command
180
     */
181
    public void addCommand(Command command);
182
    
183
    /**
184
     * Adds the given configured command to the bootstrap.
185
     * @param command a ConfiguredCommand
186
     */
187
    public void addCommand(ConfiguredCommand<T> command);
188
    
189
    /**
190
     * Returns the bootstrap's ObjectMapper.
191
     * @return the JSON object mapper
192
     */
193
    public ObjectMapper getObjectMapper();
194
    
195
    /**
196
     * Sets the ObjectMapper for the bootstrap.
197
     * @param objectMapper an ObjectMapper (should be created by Jackson.newObjectMapper())
198
     */
199
    public void setObjectMapper(ObjectMapper objectMapper);
200
    
201
    /**
202
     * Returns the application metrics.
203
     * @return the metric registry
204
     */
205
    public MetricRegistry getMetricRegistry();
206
    
207
    /**
208
     * Sets a custom registry for the application metrics.
209
     * @param metricRegistry a custom metric registry
210
     */
211
    public void setMetricRegistry(MetricRegistry metricRegistry);
212
    
213
    /**
214
     * Returns the application's validator factory.
215
     * @return the validator factory
216
     */
217
    public ValidatorFactory getValidatorFactory();
218
    
219
    /**
220
     * Sets the validator factory.
221
     * @param validatorFactory the validator factory
222
     */
223
    public void setValidatorFactory(ValidatorFactory validatorFactory);
224
    
225
    /**
226
     * Returns the configuration source provider.
227
     * @return the configuration source provider
228
     */
229
    public ConfigurationSourceProvider getConfigurationSourceProvider();
230
    
231
    /**
232
     * Sets the configuration source provider.
233
     * @param provider the configuration source provider
234
     */
235
    public void setConfigurationSourceProvider(ConfigurationSourceProvider provider);
236
    
237
    /**
238
     * Returns the bootstrap's class loader.
239
     * @return the class loader
240
     */
241
    public ClassLoader getClassLoader();
242
    
243
    /**
244
     * Sets the bootstrap's class loader.
245
     * @param classLoader the class loader
246
     */
247
    public void setClassLoader(ClassLoader classLoader);
248
    
249
    /**
250
     * Returns the configuration factory factory.
251
     * @return the configuration factory factory
252
     */
253
    public ConfigurationFactoryFactory<T> getConfigurationFactoryFactory();
254
    
255
    /**
256
     * Sets the configuration factory factory.
257
     * @param configurationFactoryFactory the configuration factory factory
258
     */
259
    public void setConfigurationFactoryFactory(ConfigurationFactoryFactory<T> configurationFactoryFactory);
260
    
261
    /**
262
     * Returns the health check registry.
263
     * @return the health check registry
264
     */
265
    public HealthCheckRegistry getHealthCheckRegistry();
266
    
267
    /**
268
     * Sets the health check registry.
269
     * @param healthCheckRegistry the health check registry
270
     */
271
    public void setHealthCheckRegistry(HealthCheckRegistry healthCheckRegistry);
272
    
273
    /**
274
     * Returns the JMX reporter for metrics.
275
     * @return the JmxReporter (nullable)
276
     */
277
    public JmxReporter getJmxReporter();
278
    
279
    /**
280
     * Returns the application's commands.
281
     * @return list of registered commands
282
     */
283
    public List<Command> getCommands();
284
    
285
    /**
286
     * Registers JVM metrics and starts JMX reporting.
287
     */
288
    public void registerMetrics();
289
    
290
    /**
291
     * Runs the bootstrap's bundles with the given configuration and environment.
292
     * @param configuration the parsed configuration
293
     * @param environment the application environment
294
     * @throws Exception if a bundle throws an exception
295
     */
296
    public void run(T configuration, Environment environment) throws Exception;
297
}
298
```
299

300
**Usage Examples:**
301

302
```java
303
@Override
304
public void initialize(Bootstrap<MyConfiguration> bootstrap) {
305
    // Add bundles for additional functionality
306
    bootstrap.addBundle(new AssetsBundle("/assets/", "/ui/", "index.html"));
307
    bootstrap.addBundle(new SslReloadBundle());
308
    bootstrap.addBundle(new MigrationsBundle<MyConfiguration>() {
309
        @Override
310
        public DataSourceFactory getDataSourceFactory(MyConfiguration configuration) {
311
            return configuration.getDataSourceFactory();
312
        }
313
    });
314
    
315
    // Add custom commands
316
    bootstrap.addCommand(new RenderCommand());
317
    bootstrap.addCommand(new DbMigrateCommand<>("db migrate", this, "migrations.xml"));
318
    
319
    // Customize object mapper
320
    bootstrap.getObjectMapper().disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
321
    
322
    // Set custom configuration source provider (e.g., for environment variables)
323
    bootstrap.setConfigurationSourceProvider(
324
        new SubstitutingSourceProvider(
325
            bootstrap.getConfigurationSourceProvider(),
326
            new EnvironmentVariableSubstitutor(false)
327
        )
328
    );
329
}
330
```
331

332
### AdminEnvironment Class
333

334
Administrative environment extending ServletEnvironment for the admin interface, providing task registration and health check management.
335

336
```java { .api }
337
/**
338
 * The administrative environment of a Dropwizard application.
339
 */
340
public class AdminEnvironment extends ServletEnvironment {
341
    /**
342
     * Creates a new AdminEnvironment.
343
     * @param handler a servlet context handler
344
     * @param healthChecks a health check registry
345
     * @param metricRegistry a metric registry
346
     * @param adminFactory admin factory configuration
347
     */
348
    public AdminEnvironment(MutableServletContextHandler handler,
349
                           HealthCheckRegistry healthChecks,
350
                           MetricRegistry metricRegistry,
351
                           AdminFactory adminFactory);
352
    
353
    /**
354
     * Adds the given task to the admin environment.
355
     * @param task an administrative task
356
     */
357
    public void addTask(Task task);
358
    
359
    /**
360
     * Returns the health check registry.
361
     * @return the health check registry
362
     */
363
    public HealthCheckRegistry getHealthChecks();
364
    
365
    /**
366
     * Returns the task servlet.
367
     * @return the task servlet for admin tasks
368
     */
369
    public TaskServlet getTasks();
370
}
371
```
372

373
**Usage Examples:**
374

375
```java
376
// Register admin tasks
377
environment.admin().addTask(new GarbageCollectionTask());
378
environment.admin().addTask(new LogConfigurationTask());
379
environment.admin().addTask(new CacheFlushTask(cacheManager));
380

381
// Register admin servlets
382
environment.admin().addServlet("custom-admin", new CustomAdminServlet())
383
    .addMapping("/admin/custom/*");
384
```
385

386
## Types
387

388
```java { .api }
389
// Core environment interfaces from related modules
390
public interface JerseyEnvironment {
391
    void register(Object component);
392
    void register(Class<?> componentClass);
393
}
394

395
public interface ServletEnvironment {
396
    ServletRegistration.Dynamic addServlet(String name, Servlet servlet);
397
    FilterRegistration.Dynamic addFilter(String name, Filter filter);
398
}
399

400
public interface LifecycleEnvironment {
401
    void manage(Managed managed);
402
    ExecutorServiceBuilder executorService(String nameFormat);
403
}
404

405
public interface HealthEnvironment {
406
    void register(String name, HealthCheck healthCheck);
407
}
408
```