0
# Core Application Framework
1

2
The core application framework provides the foundation classes for building Dropwizard applications, including the main Application class, Configuration system, and runtime Environment management.
3

4
## Capabilities
5

6
### Application Class
7

8
The abstract base class that serves as the main entry point for all Dropwizard applications, defining application lifecycle methods and providing command-line interface support.
9

10
```java { .api }
11
package io.dropwizard.core;
12

13
public abstract class Application<T extends Configuration> {
14
    /**
15
     * Returns the name of the application.
16
     */
17
    public abstract String getName();
18
    
19
    /**
20
     * Initializes the application bootstrap.
21
     * Called before the application runs, used to register bundles and commands.
22
     */
23
    public void initialize(Bootstrap<T> bootstrap) {}
24
    
25
    /**
26
     * Runs the application with the given configuration and environment.
27
     * This is where you register resources, health checks, and other components.
28
     */
29
    public abstract void run(T configuration, Environment environment) throws Exception;
30
    
31
    /**
32
     * Parses command-line arguments and runs the application.
33
     */
34
    public final void run(String... arguments) throws Exception;
35
    
36
    /**
37
     * Main entry point for command-line execution.
38
     */
39
    public static void main(String[] args) throws Exception;
40
}
41
```
42

43
**Usage Example:**
44

45
```java
46
public class MyApplication extends Application<MyConfiguration> {
47
    public static void main(String[] args) throws Exception {
48
        new MyApplication().run(args);
49
    }
50
    
51
    @Override
52
    public String getName() {
53
        return "my-service";
54
    }
55
    
56
    @Override
57
    public void initialize(Bootstrap<MyConfiguration> bootstrap) {
58
        bootstrap.addBundle(new AssetsBundle());
59
        bootstrap.addCommand(new MyCustomCommand());
60
    }
61
    
62
    @Override
63
    public void run(MyConfiguration configuration, Environment environment) {
64
        final MyResource resource = new MyResource(configuration.getMessage());
65
        environment.jersey().register(resource);
66
        
67
        final MyHealthCheck healthCheck = new MyHealthCheck();
68
        environment.healthChecks().register("my-health-check", healthCheck);
69
    }
70
}
71
```
72

73
### Configuration System
74

75
Base configuration class that provides framework-level configuration options including server settings, logging, metrics, and administrative interface configuration.
76

77
```java { .api }
78
package io.dropwizard.core;
79

80
@JsonIgnoreProperties(ignoreUnknown = true)
81
public class Configuration {
82
    @Valid
83
    @NotNull
84
    private ServerFactory server = new DefaultServerFactory();
85
    
86
    @Valid
87
    @NotNull
88
    private LoggingFactory logging = new DefaultLoggingFactory();
89
    
90
    @Valid
91
    @NotNull
92
    private MetricsFactory metrics = new DefaultMetricsFactory();
93
    
94
    public ServerFactory getServerFactory();
95
    public void setServerFactory(ServerFactory factory);
96
    
97
    public LoggingFactory getLoggingFactory();
98
    public void setLoggingFactory(LoggingFactory factory);
99
    
100
    public MetricsFactory getMetricsFactory();
101
    public void setMetricsFactory(MetricsFactory factory);
102
}
103
```
104

105
**Usage Example:**
106

107
```java
108
public class MyConfiguration extends Configuration {
109
    @NotEmpty
110
    private String message = "Hello, World!";
111
    
112
    @Valid
113
    @NotNull
114
    private DataSourceFactory database = new DataSourceFactory();
115
    
116
    @JsonProperty
117
    public String getMessage() { return message; }
118
    
119
    @JsonProperty
120
    public void setMessage(String message) { this.message = message; }
121
    
122
    @JsonProperty("database")
123
    public DataSourceFactory getDataSourceFactory() { return database; }
124
    
125
    @JsonProperty("database")
126
    public void setDataSourceFactory(DataSourceFactory factory) { this.database = factory; }
127
}
128
```
129

130
### Environment
131

132
The runtime container that provides access to Jersey, servlets, admin interface, lifecycle management, metrics, and health checks.
133

134
```java { .api }
135
package io.dropwizard.core.setup;
136

137
public class Environment {
138
    /**
139
     * Returns the Jersey (JAX-RS) environment for registering resources and providers.
140
     */
141
    public JerseyEnvironment jersey();
142
    
143
    /**
144
     * Returns the servlet environment for servlet registration.
145
     */
146
    public ServletEnvironment servlets();
147
    
148
    /**
149
     * Returns the admin environment for administrative servlets and resources.
150
     */
151
    public AdminEnvironment admin();
152
    
153
    /**
154
     * Returns the lifecycle environment for managing application lifecycle.
155
     */
156
    public LifecycleEnvironment lifecycle();
157
    
158
    /**
159
     * Returns the health check registry for application health monitoring.
160
     */
161
    public HealthCheckRegistry healthChecks();
162
    
163
    /**
164
     * Returns the metric registry for application metrics collection.
165
     */
166
    public MetricRegistry metrics();
167
    
168
    /**
169
     * Returns the Jackson ObjectMapper for JSON serialization configuration.
170
     */
171
    public ObjectMapper getObjectMapper();
172
    
173
    /**
174
     * Returns the validator factory for input validation.
175
     */
176
    public Validator getValidator();
177
}
178
```
179

180
### Bootstrap
181

182
Pre-start application environment used for registering bundles, commands, and configuring the application before it runs.
183

184
```java { .api }
185
package io.dropwizard.core.setup;
186

187
public class Bootstrap<T extends Configuration> {
188
    /**
189
     * Adds a bundle to the application.
190
     */
191
    public void addBundle(Bundle bundle);
192
    
193
    /**
194
     * Adds a configuration-aware bundle to the application.
195
     */
196
    public void addBundle(ConfiguredBundle<? super T> bundle);
197
    
198
    /**
199
     * Adds a command to the application.
200
     */
201
    public void addCommand(Command command);
202
    
203
    /**
204
     * Adds a configuration-aware command to the application.
205
     */
206
    public void addCommand(ConfiguredCommand<T> command);
207
    
208
    /**
209
     * Sets the application's ObjectMapper.
210
     */
211
    public void setObjectMapper(ObjectMapper objectMapper);
212
    
213
    /**
214
     * Sets the configuration source provider.
215
     */
216
    public void setConfigurationSourceProvider(ConfigurationSourceProvider provider);
217
    
218
    /**
219
     * Returns the application instance.
220
     */
221
    public Application<T> getApplication();
222
    
223
    /**
224
     * Returns the configuration class.
225
     */
226
    public Class<T> getConfigurationClass();
227
}
228
```
229

230
**Usage Example:**
231

232
```java
233
@Override
234
public void initialize(Bootstrap<MyConfiguration> bootstrap) {
235
    // Add bundles for additional functionality
236
    bootstrap.addBundle(new AssetsBundle("/assets/", "/static/"));
237
    bootstrap.addBundle(new ViewBundle<>());
238
    
239
    // Add custom commands
240
    bootstrap.addCommand(new MyCustomCommand<>());
241
    
242
    // Configure ObjectMapper for JSON processing
243
    bootstrap.getObjectMapper().registerModule(new JavaTimeModule());
244
    
245
    // Enable environment variable substitution in configuration
246
    bootstrap.setConfigurationSourceProvider(
247
        new SubstitutingSourceProvider(
248
            bootstrap.getConfigurationSourceProvider(),
249
            new EnvironmentVariableSubstitutor(false)
250
        )
251
    );
252
}
253
```
254

255
## Lifecycle Management
256

257
### Managed Objects
258

259
Dropwizard provides lifecycle management through the `Managed` interface for components that need to be started and stopped with the application.
260

261
```java { .api }
262
package io.dropwizard.lifecycle;
263

264
public interface Managed {
265
    /**
266
     * Starts the managed object. Called when the application starts.
267
     */
268
    void start() throws Exception;
269
    
270
    /**
271
     * Stops the managed object. Called when the application stops.
272
     */
273
    void stop() throws Exception;
274
}
275
```
276

277
**Usage Example:**
278

279
```java
280
public class DatabaseConnectionManager implements Managed {
281
    private Connection connection;
282
    
283
    @Override
284
    public void start() throws Exception {
285
        connection = DriverManager.getConnection("jdbc:...");
286
    }
287
    
288
    @Override
289
    public void stop() throws Exception {
290
        if (connection != null) {
291
            connection.close();
292
        }
293
    }
294
}
295

296
// Register in application
297
@Override
298
public void run(MyConfiguration configuration, Environment environment) {
299
    environment.lifecycle().manage(new DatabaseConnectionManager());
300
}
301
```
302

303
### Server Lifecycle Events
304

305
Monitor server lifecycle events to perform actions when the server starts, stops, or fails.
306

307
```java { .api }
308
package io.dropwizard.lifecycle;
309

310
public interface ServerLifecycleListener {
311
    /**
312
     * Called when the server has successfully started.
313
     */
314
    void serverStarted(Server server);
315
}
316
```