Organizing Your Project

In general, we recommend you separate your projects into three Maven modules: project-api, project-client, and project-application.

project-api should contain your Representations; project-client should use those classes and an HTTP client to implement a full-fledged client for your application, and project-application should provide the actual application implementation, including Resources.

Our applications tend to look like this:

• com.example.myapplication:
  • api: Representations.
  • cli: Commands
  • client: Client implementation for your application
  • core: Domain implementation
  • jdbi: Database access classes
  • health: Health Checks
  • resources: Resources
  • MyApplication: The application class
  • MyApplicationConfiguration: configuration class

Application

The main entry point into a Dropwizard application is, unsurprisingly, the Application class. Each Application has a name, which is mostly used to render the command-line interface. In the constructor of your Application you can add Bundles and Commands to your application.

Configuration

Dropwizard provides a number of built-in configuration parameters. They are well documented in the example project’s configuration.

Each Application subclass has a single type parameter: that of its matching Configuration subclass. These are usually at the root of your application’s main package. For example, your User application would have two classes: UserApplicationConfiguration, extending Configuration, and UserApplication, extending Application<UserApplicationConfiguration>.

When your application runs Configured Commands like the server command, Dropwizard parses the provided YAML configuration file and builds an instance of your application’s configuration class by mapping YAML field names to object field names.

In order to keep your configuration file and class manageable, we recommend grouping related configuration parameters into independent configuration classes. If your application requires a set of configuration parameters in order to connect to a message queue, for example, we recommend that you create a new MessageQueueFactory class:

public class MessageQueueFactory {
    @NotEmpty
    private String host;

    @Min(1)
    @Max(65535)
    private int port = 5672;

    @JsonProperty
    public String getHost() {
        return host;
    }

    @JsonProperty
    public void setHost(String host) {
        this.host = host;
    }

    @JsonProperty
    public int getPort() {
        return port;
    }

    @JsonProperty
    public void setPort(int port) {
        this.port = port;
    }

    public MessageQueueClient build(Environment environment) {
        MessageQueueClient client = new MessageQueueClient(getHost(), getPort());
        environment.lifecycle().manage(new Managed() {
            @Override
            public void start() {
            }

            @Override
            public void stop() {
                client.close();
            }
        };
        return client;
    }
}

In this example our factory will automatically tie our MessageQueueClient connection to the lifecycle of our application’s Environment.

Your main Configuration subclass can then include this as a member field:

public class ExampleApplicationConfiguration extends Configuration {
    @Valid
    @NotNull
    private MessageQueueFactory messageQueue = new MessageQueueFactory();

    @JsonProperty("messageQueue")
    public MessageQueueFactory getMessageQueueFactory() {
        return messageQueue;
    }

    @JsonProperty("messageQueue")
    public void setMessageQueueFactory(MessageQueueFactory factory) {
        this.messageQueue = factory;
    }
}

And your Application subclass can then use your factory to directly construct a client for the message queue:

public void run(ExampleConfiguration configuration,
                Environment environment) {
    MessageQueueClient messageQueue = configuration.getMessageQueueFactory().build(environment);
}

Then, in your application’s YAML file, you can use a nested messageQueue field:

messageQueue:
  host: mq.example.com
  port: 5673

The @NotNull, @NotEmpty, @Min, @Max, and @Valid annotations are part of Dropwizard’s Validation functionality. If your YAML configuration file’s messageQueue.host field was missing (or was a blank string), Dropwizard would refuse to start and would output an error message describing the issues.

Once your application has parsed the YAML file and constructed its Configuration instance, Dropwizard then calls your Application subclass to initialize your application’s Environment.

server:
  applicationConnectors:
    - type: https
      port: 8443
      keyStorePath: example.keystore
      keyStorePassword: example
      validateCerts: false

Bootstrapping

Before a Dropwizard application can provide the command-line interface, parse a configuration file, or run as a server, it must first go through a bootstrapping phase. This phase corresponds to your Application subclass’s initialize method. You can add Bundles, Commands, or register Jackson modules to allow you to include custom types as part of your configuration class.

Environments

A Dropwizard Environment consists of all the Resources, servlets, filters, Health Checks, Jersey providers, Managed Objects, Tasks, and Jersey properties which your application provides.

Each Application subclass implements a run method. This is where you should be creating new resource instances, etc., and adding them to the given Environment class:

@Override
public void run(ExampleConfiguration config,
                Environment environment) {
    // encapsulate complicated setup logic in factories
    final Thingy thingy = config.getThingyFactory().build();

    environment.jersey().register(new ThingyResource(thingy));
    environment.healthChecks().register(new ThingyHealthCheck(thingy));
}

It’s important to keep the run method clean, so if creating an instance of something is complicated, like the Thingy class above, extract that logic into a factory.

Health Checks

A health check is a runtime test which you can use to verify your application’s behavior in its production environment. For example, you may want to ensure that your database client is connected to the database:

public class DatabaseHealthCheck extends HealthCheck {
    private final Database database;

    public DatabaseHealthCheck(Database database) {
        super("database");
        this.database = database;
    }

    @Override
    protected Result check() throws Exception {
        if (database.isConnected()) {
            return Result.healthy();
        } else {
            return Result.unhealthy("Cannot connect to " + database.getUrl());
        }
    }
}

You can then add this health check to your application’s environment:

environment.healthChecks().register(new DatabaseHealthCheck(database));

By sending a GET request to /healthcheck on the admin port you can run these tests and view the results:

$ curl http://dw.example.com:8081/healthcheck
* deadlocks: OK
* database: OK

If all health checks report success, a 200 OK is returned. If any fail, a 500 Internal Server Error is returned with the error messages and exception stack traces (if an exception was thrown).

All Dropwizard applications ship with the deadlocks health check installed by default, which uses Java 1.6’s built-in thread deadlock detection to determine if any threads are deadlocked.

Managed Objects

Most applications involve objects which need to be started and stopped: thread pools, database connections, etc. Dropwizard provides the Managed interface for this. You can either have the class in question implement the #start() and #stop() methods, or write a wrapper class which does so. Adding a Managed instance to your application’s Environment ties that object’s lifecycle to that of the application’s HTTP server. Before the server starts, the #start() method is called. After the server has stopped (and after its graceful shutdown period) the #stop() method is called.

For example, given a theoretical Riak client which needs to be started and stopped:

public class RiakClientManager implements Managed {
    private final RiakClient client;

    public RiakClientManager(RiakClient client) {
        this.client = client;
    }

    @Override
    public void start() throws Exception {
        client.start();
    }

    @Override
    public void stop() throws Exception {
        client.stop();
    }
}

public class MyApplication extends Application<MyConfiguration>{
    @Override
    public void run(MyApplicationConfiguration configuration, Environment environment) {
        RiakClient client = ...;
        RiakClientManager riakClientManager = new RiakClientManager(client);
        environment.lifecycle().manage(riakClientManager);
    }
}

If RiakClientManager#start() throws an exception–e.g., an error connecting to the server–your application will not start and a full exception will be logged. If RiakClientManager#stop() throws an exception, the exception will be logged but your application will still be able to shut down.

It should be noted that Environment has built-in factory methods for ExecutorService and ScheduledExecutorService instances which are managed. See LifecycleEnvironment#executorService and LifecycleEnvironment#scheduledExecutorService for details.

Bundles

A Dropwizard bundle is a reusable group of functionality, used to define blocks of an application’s behavior. For example, AssetBundle provides a simple way to serve static assets from your application’s src/main/resources/assets directory as files available from /assets/* in your application.

Some bundles require configuration parameters. These bundles implement ConfiguredBundle and will require your application’s Configuration subclass to implement a specific interface.

server:
  type: simple
  applicationContextPath: /application/*  # Default value*

@Override
public void initialize(Bootstrap<HelloWorldConfiguration> bootstrap) {
    bootstrap.addBundle(new AssetsBundle("/assets/", "/"));
}

Commands

Commands are basic actions which Dropwizard runs based on the arguments provided on the command line. The built-in server command, for example, spins up an HTTP server and runs your application. Each Command subclass has a name and a set of command line options which Dropwizard will use to parse the given command line arguments.

public class MyApplication extends Application<MyConfiguration>{
    @Override
    public void initialize(Bootstrap<DropwizardConfiguration> bootstrap) {
        bootstrap.addCommand(new MyCommand());
    }
}

Tasks

A Task is a run-time action your application provides access to on the administrative port via HTTP. All Dropwizard applications start with the gc task, which explicitly triggers the JVM’s garbage collection. (This is useful, for example, for running full garbage collections during off-peak times or while the given application is out of rotation.)

Running a task can be done by sending a POST request to /tasks/{task-name} on the admin port. For example:

$ curl -X POST http://dw.example.com:8081/tasks/gc
Running GC...
Done!

Logging

Dropwizard uses Logback for its logging backend. It provides an slf4j implementation, and even routes all java.util.logging, Log4j, and Apache Commons Logging usage through Logback.

slf4j provides the following logging levels:

ERROR

Error events that might still allow the application to continue running.

WARN

Potentially harmful situations.

INFO

Informational messages that highlight the progress of the application at coarse-grained level.

DEBUG

Fine-grained informational events that are most useful to debug an application.

TRACE

Finer-grained informational events than the DEBUG level.

TRACE [2010-04-06 06:42:35,271] com.example.dw.Thing: Contemplating doing a thing.
DEBUG [2010-04-06 06:42:35,274] com.example.dw.Thing: About to do a thing.
INFO  [2010-04-06 06:42:35,274] com.example.dw.Thing: Doing a thing
WARN  [2010-04-06 06:42:35,275] com.example.dw.Thing: Doing a thing
ERROR [2010-04-06 06:42:35,275] com.example.dw.Thing: This may get ugly.
! java.lang.RuntimeException: oh noes!
! at com.example.dw.Thing.run(Thing.java:16)
!

# Logging settings.
logging:

  # The default level of all loggers. Can be OFF, ERROR, WARN, INFO, DEBUG, TRACE, or ALL.
  level: INFO

  # Logger-specific levels.
  loggers:

    # Overrides the level of com.example.dw.Thing and sets it to DEBUG.
    "com.example.dw.Thing": DEBUG

logging:
  appenders:
    - type: console
      threshold: WARN
      target: stderr

logging:

  appenders:
    - type: file
      # The file to which current statements will be logged.
      currentLogFilename: ./logs/example.log

      # When the log file rotates, the archived log will be renamed to this and gzipped. The
      # %d is replaced with the previous day (yyyy-MM-dd). Custom rolling windows can be created
      # by passing a SimpleDateFormat-compatible format as an argument: "%d{yyyy-MM-dd-hh}".
      archivedLogFilenamePattern: ./logs/example-%d.log.gz

      # The number of archived files to keep.
      archivedFileCount: 5

      # The timezone used to format dates. HINT: USE THE DEFAULT, UTC.
      timeZone: UTC

logging:

  appenders:
    - type: syslog
      # The hostname of the syslog server to which statements will be sent.
      # N.B.: If this is the local host, the local syslog instance will need to be configured to
      # listen on an inet socket, not just a Unix socket.
      host: localhost

      # The syslog facility to which statements will be sent.
      facility: local0

logging:

  # Permit DEBUG, INFO, WARN and ERROR messages to be logged by appenders.
  level: DEBUG

  appenders:
    # Log warnings and errors to stderr
    - type: console
      threshold: WARN
      target: stderr

    # Log info, warnings and errors to our apps' main log.
    # Rolled over daily and retained for 5 days.
    - type: file
      threshold: INFO
      currentLogFilename: ./logs/example.log
      archivedLogFilenamePattern: ./logs/example-%d.log.gz
      archivedFileCount: 5

    # Log debug messages, info, warnings and errors to our apps' debug log.
    # Rolled over hourly and retained for 6 hours
    - type: file
      threshold: DEBUG
      currentLogFilename: ./logs/debug.log
      archivedLogFilenamePattern: ./logs/debug-%d{yyyy-MM-dd-hh}.log.gz
      archivedFileCount: 6

Testing Applications

All of Dropwizard’s APIs are designed with testability in mind, so even your applications can have unit tests:

public class MyApplicationTest {
    private final Environment environment = mock(Environment.class);
    private final MyApplication application = new MyApplication();
    private final MyConfiguration config = new MyConfiguration();

    @Before
    public void setup() throws Exception {
        config.setMyParam("yay");
    }

    @Test
    public void buildsAThingResource() throws Exception {
        application.run(config, environment);

        verify(environment).jersey().register(any(ThingResource.class));
    }
}

We highly recommend Mockito for all your mocking needs.

Banners

We think applications should print out a big ASCII art banner on startup. Yours should, too. It’s fun. Just add a banner.txt class to src/main/resources and it’ll print it out when your application starts:

INFO  [2011-12-09 21:56:37,209] io.dropwizard.cli.ServerCommand: Starting hello-world
                                                 dP
                                                 88
  .d8888b. dP.  .dP .d8888b. 88d8b.d8b. 88d888b. 88 .d8888b.
  88ooood8  `8bd8'  88'  `88 88'`88'`88 88'  `88 88 88ooood8
  88.  ...  .d88b.  88.  .88 88  88  88 88.  .88 88 88.  ...
  `88888P' dP'  `dP `88888P8 dP  dP  dP 88Y888P' dP `88888P'
                                        88
                                        dP

INFO  [2011-12-09 21:56:37,214] org.eclipse.jetty.server.Server: jetty-7.6.0
...

We could probably make up an argument about why this is a serious devops best practice with high ROI and an Agile Tool, but honestly we just enjoy this.

We recommend you use TAAG for all your ASCII art banner needs.

Resources

Unsurprisingly, most of your day-to-day work with a Dropwizard application will be in the resource classes, which model the resources exposed in your RESTful API. Dropwizard uses Jersey for this, so most of this section is just re-hashing or collecting various bits of Jersey documentation.

Jersey is a framework for mapping various aspects of incoming HTTP requests to POJOs and then mapping various aspects of POJOs to outgoing HTTP responses. Here’s a basic resource class:

@Path("/{user}/notifications")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class NotificationsResource {
    private final NotificationStore store;

    public NotificationsResource(NotificationStore store) {
        this.store = store;
    }

    @GET
    public NotificationList fetch(@PathParam("user") LongParam userId,
                                  @QueryParam("count") @DefaultValue("20") IntParam count) {
        final List<Notification> notifications = store.fetch(userId.get(), count.get());
        if (notifications != null) {
            return new NotificationList(userId, notifications);
        }
        throw new WebApplicationException(Status.NOT_FOUND);
    }

    @POST
    public Response add(@PathParam("user") LongParam userId,
                        @Valid Notification notification) {
        final long id = store.add(userId.get(), notification);
        return Response.created(UriBuilder.fromResource(NotificationResource.class)
                                          .build(userId.get(), id))
                       .build();
    }
}

This class provides a resource (a user’s list of notifications) which responds to GET and POST requests to /{user}/notifications, providing and consuming application/json representations. There’s quite a lot of functionality on display here, and this section will explain in detail what’s in play and how to use these features in your application.

@POST
public Response add(@PathParam("user") LongParam userId,
                    @Valid Notification notification) {
    final long id = store.add(userId.get(), notification);
    return Response.created(UriBuilder.fromResource(NotificationResource.class)
                                      .build(userId.get(), id)
                   .build();
}

return Response.noContent().language(Locale.GERMAN).build();

UriBuilder.fromResource(UserResource.class).build(user.getId());

public class NotificationsResourceTest {
    private final NotificationStore store = mock(NotificationStore.class);
    private final NotificationsResource resource = new NotificationsResource(store);

    @Test
    public void getsReturnNotifications() {
        final List<Notification> notifications = mock(List.class);
        when(store.fetch(1, 20)).thenReturn(notifications);

        final NotificationList list = resource.fetch(new LongParam("1"), new IntParam("20"));

        assertThat(list.getUserId(),
                  is(1L));

        assertThat(list.getNotifications(),
                   is(notifications));
    }
}

@GET
@CacheControl(maxAge = 6, maxAgeUnit = TimeUnit.HOURS)
public String getCachableValue() {
    return "yay";
}

Representations

Representation classes are classes which, when handled to various Jersey MessageBodyReader and MessageBodyWriter providers, become the entities in your application’s API. Dropwizard heavily favors JSON, but it’s possible to map from any POJO to custom formats and back.

public class Notification {
    private String text;

    public Notification(String text) {
        this.text = text;
    }

    @JsonProperty
    public String getText() {
        return text;
    }

    @JsonProperty
    public void setText(String text) {
        this.text = text;
    }
}

{
    "text": "hey it's the value of the text field"
}

public class Notification {
    private final String text;

    @JsonCreator
    public Notification(@JsonProperty("text") String text) {
        this.text = text;
    }

    @JsonProperty("text")
    public String getText() {
        return text;
    }
}

@JsonSerialize(using=FunkySerializer.class)
@JsonDeserialize(using=FunkyDeserializer.class)
public class Funky {
    // ...
}

@JsonSnakeCase
public class Person {
    private final String firstName;

    @JsonCreator
    public Person(@JsonProperty String firstName) {
        this.firstName = firstName;
    }

    @JsonProperty
    public String getFirstName() {
        return firstName;
    }
}

{
    "first_name": "Coda"
}

public class Person {

    @NotEmpty // ensure that name isn't null or blank
    private final String name;

    @JsonCreator
    public Person(@JsonProperty("name") String name) {
        this.name = name;
    }

    @JsonProperty("name")
    public String getName() {
        return name;
    }
}

@PUT
public Response replace(@Valid Person person) {
    // ...
}

* name may not be empty

@ValidationMethod(message="may not be Coda")
public boolean isNotCoda() {
    return !("Coda".equals(name));
}

How it’s glued together

When your application starts up, it will spin up a Jetty HTTP server, see DefaultServerFactory. This server will have two handlers, one for your application port and the other for your admin port. The admin handler creates and registers the AdminServlet. This has a handle to all of the application healthchecks and metrics via the ServletContext.

The application port has an HttpServlet as well, this is composed of DropwizardResourceConfig, which is an extension of Jersey’s resource configuration that performs scanning to find root resource and provider classes. Ultimately when you call env.jersey().register(new SomeResource()), you are adding to the DropwizardResourceConfig. This config is a jersey Application, so all of your application resources are served from one Servlet

DropwizardResourceConfig is where the various ResourceMethodDispatchAdapter are registered to enable the following functionality:

• Resource method requests with @Timed, @Metered, @ExceptionMetered are delegated to special dispatchers which decorate the metric telemetry
• Resources that return Guava Optional are unboxed. Present returns underlying type, and non present 404s
• Resource methods that are annotated with @CacheControl are delegated to a special dispatcher that decorates on the cache control headers
• Enables using Jackson to parse request entities into objects and generate response entities from objects, all while performing validation