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.
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(getName());
environment.jersey().register(new ExternalServiceResource(httpClient));
}
Dropwizard’s HttpClientBuilder
actually gives you an instrumented subclass which tracks the
following pieces of data:
org.apache.http.conn.ClientConnectionManager.available-connections
org.apache.http.conn.ClientConnectionManager.leased-connections
org.apache.http.conn.ClientConnectionManager.max-connections
org.apache.http.conn.ClientConnectionManager.pending-connections
org.apache.http.client.HttpClient.get-requests
GET
requests are being sent.org.apache.http.client.HttpClient.post-requests
POST
requests are being sent.org.apache.http.client.HttpClient.head-requests
HEAD
requests are being sent.org.apache.http.client.HttpClient.put-requests
PUT
requests are being sent.org.apache.http.client.HttpClient.delete-requests
DELETE
requests are being sent.org.apache.http.client.HttpClient.options-requests
OPTIONS
requests are being sent.org.apache.http.client.HttpClient.trace-requests
TRACE
requests are being sent.org.apache.http.client.HttpClient.connect-requests
CONNECT
requests are being sent.org.apache.http.client.HttpClient.move-requests
MOVE
requests are being sent.org.apache.http.client.HttpClient.patch-requests
PATCH
requests are being sent.org.apache.http.client.HttpClient.other-requests
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
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;
}
@JsonProperty("jerseyClient")
public void setJerseyClientConfiguration(JerseyClientConfiguration jerseyClient) {
this.jerseyClient = 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));
}
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.
To increase the ergonomics of asynchronous client requests, Jersey allows creation of rx-clients. You can instruct Dropwizard to create such a client:
@Override
public void run(ExampleConfiguration config,
Environment environment) {
final RxClient<RxCompletionStageInvoker> client =
new JerseyClientBuilder(environment)
.using(config.getJerseyClientConfiguration())
.buildRx(getName(), RxCompletionStageInvoker.class);
environment.jersey().register(new ExternalServiceResource(client));
}
RxCompletionStageInvoker.class
is the Java 8 implementation and can be added to the pom:
<dependency>
<groupId>org.glassfish.jersey.ext.rx</groupId>
<artifactId>jersey-rx-client-java8</artifactId>
</dependency>
Alternatively, there are RxJava, Guava, and JSR-166e implementations.
By allowing Dropwizard to create the rx-client, the same thread pool that is utilized by traditional synchronous and asynchronous requests, is used for rx requests.
The client can utilise a forward proxy, supporting both Basic and NTLM authentication schemes. Basic Auth against a proxy is simple:
proxy:
host: '192.168.52.11'
port: 8080
scheme : 'https'
auth:
username: 'secret'
password: 'stuff'
nonProxyHosts:
- 'localhost'
- '192.168.52.*'
- '*.example.com'
NTLM Auth is configured by setting the relevant windows properties.
proxy:
host: '192.168.52.11'
port: 8080
scheme : 'https'
auth:
username: 'secret'
password: 'stuff'
authScheme: 'NTLM'
realm: 'realm' # optional, defaults to ANY_REALM
hostname: 'workstation' # optional, defaults to null but may be required depending on your AD environment
domain: 'HYPERCOMPUGLOBALMEGANET' # optional, defaults to null but may be required depending on your AD environment
credentialType: 'NT'
nonProxyHosts:
- 'localhost'
- '192.168.52.*'
- '*.example.com'