0
# Dropwizard
1
2
Dropwizard is a Java framework for developing ops-friendly, high-performance, RESTful web applications. It brings together mature Java libraries including Jetty, Jersey, Jackson, Logback, Hibernate Validator, and Metrics into a cohesive framework that enables rapid development of production-ready services with built-in operational features.
3
4
## Package Information
5
6
- **Package Name**: dropwizard-project
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add core dependency to your `pom.xml`
10
- **Group ID**: io.dropwizard
11
- **Artifact ID**: dropwizard-core
12
- **Version**: 3.0.14
13
- **License**: Apache-2.0
14
15
## Core Imports
16
17
```java
18
import io.dropwizard.core.Application;
19
import io.dropwizard.core.Configuration;
20
import io.dropwizard.core.setup.Bootstrap;
21
import io.dropwizard.core.setup.Environment;
22
```
23
24
Additional common imports:
25
26
```java
27
import javax.ws.rs.*;
28
import javax.ws.rs.core.MediaType;
29
import com.codahale.metrics.annotation.Timed;
30
import javax.validation.Valid;
31
import javax.validation.constraints.NotNull;
32
```
33
34
## Basic Usage
35
36
```java
37
// 1. Create configuration class
38
public class HelloWorldConfiguration extends Configuration {
39
@NotNull
40
private String template = "Hello, %s!";
41
42
@JsonProperty
43
public String getTemplate() { return template; }
44
45
@JsonProperty
46
public void setTemplate(String template) { this.template = template; }
47
}
48
49
// 2. Create JAX-RS resource
50
@Path("/hello-world")
51
@Produces(MediaType.APPLICATION_JSON)
52
public class HelloWorldResource {
53
private final String template;
54
55
public HelloWorldResource(String template) {
56
this.template = template;
57
}
58
59
@GET
60
@Timed
61
public Saying sayHello(@QueryParam("name") Optional<String> name) {
62
final String value = String.format(template, name.orElse("Stranger"));
63
return new Saying(value);
64
}
65
}
66
67
// 3. Create application class
68
public class HelloWorldApplication extends Application<HelloWorldConfiguration> {
69
public static void main(String[] args) throws Exception {
70
new HelloWorldApplication().run(args);
71
}
72
73
@Override
74
public String getName() {
75
return "hello-world";
76
}
77
78
@Override
79
public void initialize(Bootstrap<HelloWorldConfiguration> bootstrap) {
80
// Add bundles here
81
}
82
83
@Override
84
public void run(HelloWorldConfiguration configuration,
85
Environment environment) {
86
final HelloWorldResource resource = new HelloWorldResource(
87
configuration.getTemplate()
88
);
89
environment.jersey().register(resource);
90
}
91
}
92
```
93
94
## Architecture
95
96
Dropwizard follows a convention-over-configuration approach with several key architectural components:
97
98
- **Application Class**: Main entry point extending `Application<T>` that defines application lifecycle
99
- **Configuration**: YAML-based configuration with validation using Bean Validation (JSR-303)
100
- **Environment**: Runtime container providing access to Jersey, servlets, admin interface, lifecycle, metrics, and health checks
101
- **Bootstrap**: Pre-start setup environment for registering bundles and commands
102
- **Bundles**: Reusable application components that configure multiple aspects of the application
103
- **Managed Objects**: Lifecycle-aware components with start/stop methods for resource management
104
105
## Capabilities
106
107
### Core Application Framework
108
109
Foundation classes for building Dropwizard applications including the main Application class, Configuration system, and runtime Environment management.
110
111
```java { .api }
112
public abstract class Application<T extends Configuration> {
113
public abstract String getName();
114
public void initialize(Bootstrap<T> bootstrap) {}
115
public abstract void run(T configuration, Environment environment) throws Exception;
116
public final void run(String... arguments) throws Exception;
117
}
118
119
public class Configuration {
120
// Server configuration, logging, metrics, admin interface setup
121
}
122
123
public class Environment {
124
public JerseyEnvironment jersey();
125
public ServletEnvironment servlets();
126
public AdminEnvironment admin();
127
public LifecycleEnvironment lifecycle();
128
public HealthCheckRegistry healthChecks();
129
public MetricRegistry metrics();
130
}
131
```
132
133
[Core Application Framework](./core-application.md)
134
135
### REST API Development
136
137
Jersey (JAX-RS) integration for building RESTful web services with automatic JSON serialization, validation, and metrics collection.
138
139
```java { .api }
140
public class JerseyEnvironment {
141
public void register(Object component);
142
public void register(Class<?> componentClass);
143
public void packages(String... packages);
144
}
145
146
// Common JAX-RS annotations for resources
147
@Path("/resource")
148
@Produces(MediaType.APPLICATION_JSON)
149
@Consumes(MediaType.APPLICATION_JSON)
150
public class ResourceClass {
151
@GET @POST @PUT @DELETE
152
@Timed @Metered @Counted
153
public ResponseType method(@PathParam("id") String id,
154
@QueryParam("param") String param,
155
@Valid RequestType request);
156
}
157
```
158
159
[REST API Development](./rest-api.md)
160
161
### Configuration Management
162
163
YAML-based configuration system with environment variable substitution, validation, and type-safe access to application settings.
164
165
```java { .api }
166
public class ConfigurationFactory<T> {
167
public T build(ConfigurationSourceProvider provider, String path) throws IOException, ConfigurationException;
168
}
169
170
public interface ConfigurationSourceProvider {
171
InputStream open(String path) throws IOException;
172
}
173
174
// Configuration validation annotations
175
@NotNull @NotEmpty @Valid @Min @Max @Range
176
@DurationRange @DataSizeRange @OneOf @PortRange
177
```
178
179
[Configuration Management](./configuration.md)
180
181
### Authentication and Authorization
182
183
Pluggable authentication system supporting basic auth, OAuth, and custom authentication schemes with fine-grained authorization control.
184
185
```java { .api }
186
public interface Authenticator<C, P> {
187
Optional<P> authenticate(C credentials) throws AuthenticationException;
188
}
189
190
public interface Authorizer<P> {
191
boolean authorize(P principal, String role);
192
}
193
194
public class AuthDynamicFeature implements DynamicFeature {
195
// Register authentication filters with Jersey
196
}
197
```
198
199
[Authentication](./authentication.md)
200
201
### Database Integration
202
203
Comprehensive database support including connection pooling, ORM integration with Hibernate, lightweight SQL access with JDBI, and database migrations with Liquibase.
204
205
```java { .api }
206
public class DataSourceFactory {
207
// Database connection configuration
208
}
209
210
public class HibernateBundle<T extends Configuration> implements ConfiguredBundle<T> {
211
// Hibernate ORM integration
212
}
213
214
public class MigrationsBundle<T extends Configuration> implements ConfiguredBundle<T> {
215
// Liquibase database migrations
216
}
217
```
218
219
[Database Integration](./database.md)
220
221
### Metrics and Monitoring
222
223
Built-in application metrics collection, health checks, and operational endpoints for production monitoring and observability.
224
225
```java { .api }
226
public class MetricRegistry {
227
public Timer timer(String name);
228
public Counter counter(String name);
229
public Meter meter(String name);
230
public Histogram histogram(String name);
231
}
232
233
public abstract class HealthCheck {
234
public abstract Result check() throws Exception;
235
}
236
237
// Metric annotations
238
@Timed @Metered @Counted @Gauge
239
```
240
241
[Metrics and Monitoring](./metrics.md)
242
243
### Validation Framework
244
245
Comprehensive input validation using Bean Validation (JSR-303) with custom Dropwizard validators for durations, data sizes, and other common types.
246
247
```java { .api }
248
// Built-in validation annotations
249
@DurationRange(min = 1, minUnit = TimeUnit.SECONDS, max = 1, maxUnit = TimeUnit.HOURS)
250
@DataSizeRange(min = 1, minUnit = DataSize.Unit.KILOBYTES)
251
@OneOf({"value1", "value2", "value3"})
252
@PortRange(min = 1024, max = 65535)
253
@ValidationMethod(message = "Custom validation failed")
254
```
255
256
[Validation](./validation.md)
257
258
### Testing Support
259
260
Comprehensive testing utilities including JUnit 5 extensions for full application testing, resource testing, and database testing.
261
262
```java { .api }
263
public class DropwizardAppExtension<C extends Configuration> implements BeforeAllCallback, AfterAllCallback {
264
// Full application testing
265
}
266
267
public class ResourceExtension implements BeforeEachCallback, AfterEachCallback {
268
// Resource-level testing
269
}
270
271
public class DAOTestExtension implements BeforeEachCallback, AfterEachCallback {
272
// Database testing support
273
}
274
```
275
276
[Testing](./testing.md)
277
278
## Bundle System
279
280
Dropwizard's bundle system provides reusable application components that can configure multiple aspects of an application. Bundles are registered during the bootstrap phase and can modify both bootstrap and runtime configuration.
281
282
### Common Bundles
283
284
- **AssetsBundle**: Serve static assets (CSS, JS, images) from classpath
285
- **ViewBundle**: Template engine integration (Mustache, Freemarker)
286
- **MigrationsBundle**: Database schema migrations
287
- **HibernateBundle**: Hibernate ORM configuration
288
- **ConfiguredBundle**: Bundles that require configuration access
289
290
### Bundle Usage Pattern
291
292
```java
293
@Override
294
public void initialize(Bootstrap<MyConfiguration> bootstrap) {
295
bootstrap.addBundle(new AssetsBundle("/assets/", "/static/"));
296
bootstrap.addBundle(new ViewBundle<MyConfiguration>());
297
bootstrap.addBundle(new MigrationsBundle<MyConfiguration>() {
298
@Override
299
public DataSourceFactory getDataSourceFactory(MyConfiguration configuration) {
300
return configuration.getDatabase();
301
}
302
});
303
}
304
```