Dropwizard Client

The dropwizard-client module provides you with two different performant, instrumented HTTP clients so you can integrate your service with other web services: Apache HttpClient and Jersey Client.

Apache HttpClient

The underlying library for dropwizard-client is Apache’s HttpClient, a full-featured, well-tested HTTP client library.

To create a managed, instrumented HttpClient instance, your configuration class needs an http client configuration instance:

public class ExampleConfiguration extends Configuration {
    @Valid
    @NotNull
    private HttpClientConfiguration httpClient = new HttpClientConfiguration();

    @JsonProperty("httpClient")
    public HttpClientConfiguration getHttpClientConfiguration() {
        return httpClient;
    }

    @JsonProperty("httpClient")
    public void setHttpClientConfiguration(HttpClientConfiguration httpClient) {
        this.httpClient = httpClient;
    }
}

Then, in your application’s run method, create a new HttpClientBuilder:

@Override
public void run(ExampleConfiguration config,
                Environment environment) {
    final HttpClient httpClient = new HttpClientBuilder(environment).using(config.getHttpClientConfiguration())
                                                                    .build();
    environment.jersey().register(new ExternalServiceResource(httpClient));
}

Metrics

Dropwizard’s HttpClientBuilder actually gives you an instrumented subclass which tracks the following pieces of data:

org.apache.http.conn.ClientConnectionManager.available-connections: The number the number idle connections ready to be used to execute requests.
org.apache.http.conn.ClientConnectionManager.leased-connections: The number of persistent connections currently being used to execute requests.
org.apache.http.conn.ClientConnectionManager.max-connections: The maximum number of allowed connections.
org.apache.http.conn.ClientConnectionManager.pending-connections: The number of connection requests being blocked awaiting a free connection
org.apache.http.client.HttpClient.get-requests: The rate at which GET requests are being sent.
org.apache.http.client.HttpClient.post-requests: The rate at which POST requests are being sent.
org.apache.http.client.HttpClient.head-requests: The rate at which HEAD requests are being sent.
org.apache.http.client.HttpClient.put-requests: The rate at which PUT requests are being sent.
org.apache.http.client.HttpClient.delete-requests: The rate at which DELETE requests are being sent.
org.apache.http.client.HttpClient.options-requests: The rate at which OPTIONS requests are being sent.
org.apache.http.client.HttpClient.trace-requests: The rate at which TRACE requests are being sent.
org.apache.http.client.HttpClient.connect-requests: The rate at which CONNECT requests are being sent.
org.apache.http.client.HttpClient.move-requests: The rate at which MOVE requests are being sent.
org.apache.http.client.HttpClient.patch-requests: The rate at which PATCH requests are being sent.
org.apache.http.client.HttpClient.other-requests: The rate at which requests with none of the above methods are being sent.

Note

The naming strategy for the metrics associated requests is configurable. Specifically, the last part e.g. get-requests. What is displayed is HttpClientMetricNameStrategies.METHOD_ONLY, you can also include the host via HttpClientMetricNameStrategies.HOST_AND_METHOD or a url without query string via HttpClientMetricNameStrategies.QUERYLESS_URL_AND_METHOD

Jersey Client

If HttpClient is too low-level for you, Dropwizard also supports Jersey’s Client API. Jersey’s Client allows you to use all of the server-side media type support that your service uses to, for example, deserialize application/json request entities as POJOs.

To create a managed, instrumented JerseyClient instance, your configuration class needs an jersey client configuration instance:

public class ExampleConfiguration extends Configuration {
    @Valid
    @NotNull
    private JerseyClientConfiguration jerseyClient = new JerseyClientConfiguration();

    @JsonProperty("jerseyClient")
    public JerseyClientConfiguration getJerseyClientConfiguration() {
        return jerseyClient;
    }
}

Then, in your service’s run method, create a new JerseyClientBuilder:

@Override
public void run(ExampleConfiguration config,
                Environment environment) {

    final Client client = new JerseyClientBuilder(environment).using(config.getJerseyClientConfiguration())
                                                              .build(getName());
    environment.jersey().register(new ExternalServiceResource(client));
}

Configuration

The Client that Dropwizard creates deviates from the Jersey Client Configuration defaults. The default, in Jersey, is for a client to never timeout reading or connecting in a request, while in Dropwizard, the default is 500 milliseconds.

There are a couple of ways to change this behavior. The recommended way is to modify the YAML configuration. Alternatively, set the properties on the JerseyClientConfiguration, which will take effect for all built clients. On a per client basis, the configuration can be changed by utilizing the property method and, in this case, the Jersey Client Properties can be used.

Warning

Do not try to change Jersey properties using Jersey Client Properties through the

withProperty(String propertyName, Object propertyValue)

method on the JerseyClientBuilder, because by default it’s configured by Dropwizard’s HttpClientBuilder, so the Jersey properties are ignored.