httpclient

Library providing convenience methods for accessing web resources via HTTP.

Based on the Jersey REST framework.

Maven

Add the dependency to your Maven pom.xml

<dependency>
  <groupId>dk.dbc</groupId>
  <artifactId>dbc-commons-httpclient</artifactId>
  <version>5.0-SNAPSHOT</version>
</dependency>

Usage

Since version 5.0 the use of User-Agent headers is mandatory.

In your Java code

import dk.dbc.commons.useragent.UserAgent;
import dk.dbc.httpclient;

UserAgent ua = UserAgent.forExternalRequests(); // alternatively UserAgent.forInternalRequests();
HttpClient httpClient = HttpClient.create(HttpClient.newClient(), ua);

GET requests:

try (final Response response = new HttpGet(httpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements("path", "to", "resource")
            .withQueryParameter("key", "value")
            .withHeader("Accept", "application/json")
            .execute()) {

    // do something with the response...
}

// or

try (final Response response = new HttpGet(httpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements("path", "to", "resource")
            .withQueryParameter("key", "value")
            .withHeader("Accept", "application/json")
            .executeAndExpect(Response.Status.NO_CONTENT)) {

    // do something with the response...
}

// or

MyEntity entity = new HttpGet(httpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements("path", "to", "resource")
            .withQueryParameter("key", "value")
            .withHeader("Accept", "application/json")
            .executeAndExpect(MyEntity.class);

POST requests:

try (final Response response = new HttpPost(httpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements("path", "to", "resource")
            .withData(obj, MediaType.APPLICATION_JSON)
            .withHeader("User-Agent", "MyAwesomeJavaClient")
            .withHeader("ETag", "1234")
            .execute()) {

    // do something with the response...
}

PUT requests:

try (final Response response = new HttpPut(httpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements("path", "to", "resource")
            .withData(obj, MediaType.APPLICATION_JSON)
            .withHeader("User-Agent", "StillAnAwesomeJavaClient")
            .execute()) {

    // do something with the response...
}

DELETE requests:

try (final Response response = new HttpDelete(httpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements("path", "to", "resource", "id")
            .execute()) {

    // do something with the response...
}

HEAD requests:

try (final Response response = new HttpHead(httpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements("path", "to", "resource", "id")
            .execute()) {

    // do something with the response...
}

OPTIONS requests:

try (final Response response = new HttpOptions(httpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements("path", "to", "resource", "id")
            .execute()) {

    // do something with the response...
}

HTTP requests can also be executed in a fail-safe manner with automatic retry functionality.

Note that the FailSafeHttpClient will forcibly override a RetryPolicy.onRetry() listener set by the client, unless the three argument create() method is used with the overrideOnRetry flag set to false.

import dk.dbc.httpclient.FailSafeHttpClient;

final RetryPolicy<Response> retryPolicy = new RetryPolicy<Response>()
        .handle(ProcessingException.class)
        .handleResultIf(response -> response.getStatus() == 404 || response.getStatus() == 500)
        .withDelay(Duration.ofSeconds(1))
        .withMaxRetries(3);

final FailSafeHttpClient failSafeHttpClient = FailSafeHttpClient.create(HttpClient.newClient(), ua, retryPolicy);

try (final Response response = new HttpGet(failSafeHttpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements("path", "to", "resource")
            .withQueryParameter("key", "value")
            .withHeader("Accept", "text/html")
            .execute()) {

    // do something with the response...
}

Resource paths containing variables can be interpolated using the PathBuilder class.

final PathBuilder path = new PathBuilder("path/to/resource/{id}")
            .bind("id", "id42");

try (final Response response = new HttpGet(httpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements(path.build())
            .execute()) {

    // do something with the response...
}

Compression

The client supports Brotli and GZip (de)compression. While Brotli is the newest and fastest option GZip is the more widespread. Http compression works by the client suggesting which algorithmens it can decode, with the "Accept-Encoding" header, and the server then specifies its choice with the "Content-Encoding" header. If you enable encoding the client will decompress the body automatically.

httpClient.enableCompression();
MyEntity entity = new HttpGet(httpClient)
            .withBaseUrl("http://somehost:someport")
            .withPathElements("path", "to", "resource")
            .withQueryParameter("key", "value")
            .withHeader("Accept", "application/json")
            .withCompression(Decompressor.BR, Decompressor.GZIP)
            .executeAndExpect(MyEntity.class);

Development

Requirements

To build this project JDK 21 or higher and Apache Maven are required.

License

Copyright © 2018-2025 DBC Digital A/S See license text in LICENSE.txt