Package org.apache.hc.client5.http.rest

Class RestClientBuilder

java.lang.Object
org.apache.hc.client5.http.rest.RestClientBuilder
public final class RestClientBuilder extends Object
Builds type-safe REST client proxies from Jakarta REST annotated interfaces. The proxy translates each method call into an HTTP request executed through the async CloseableHttpAsyncClient transport, which supports both HTTP/1.1 and HTTP/2.

Minimal usage:

 try (CloseableHttpAsyncClient client = HttpAsyncClients.createDefault()) {
     client.start();
     UserApi api = RestClientBuilder.newBuilder()
             .baseUri("...")
             .httpClient(client)
             .build(UserApi.class);
     String json = api.getUser(42);
 }

Both baseUri and httpClient are required. The caller owns the client lifecycle, including the call to start() before use.

Methods may return String, byte[], void, any type deserializable by the configured Jackson ObjectMapper, or Response. Any of these may also be wrapped in CompletionStage or CompletableFuture for non-blocking dispatch. Request bodies may be String, byte[], or any type serializable by the ObjectMapper.

Non-2xx responses throw ResponseProcessingException (or complete the stage exceptionally with one) unless the method returns Response, in which case the response is delivered to the caller for direct inspection.

Response entities are buffered in memory and decoded on demand by readEntity(...).

Since:
5.7

  • Method Details

    • newBuilder

      public static RestClientBuilder newBuilder()
      Creates a new builder instance.
      Returns:
      a fresh builder.

    • baseUri

      public RestClientBuilder baseUri(String uri)
      Sets the base URI for all requests.
      Parameters:
      uri - the base URI string, must not be null.
      Returns:
      this builder for chaining.

    • baseUri

      public RestClientBuilder baseUri(URI uri)
      Sets the base URI for all requests.
      Parameters:
      uri - the base URI, must not be null.
      Returns:
      this builder for chaining.

    • httpClient

      public RestClientBuilder httpClient(CloseableHttpAsyncClient client)
      Sets the async HTTP client to use for requests. The caller owns the client lifecycle, including the call to CloseableHttpAsyncClient.start().
      Parameters:
      client - the async HTTP client, must not be null.
      Returns:
      this builder for chaining.
      Since:
      5.7

    • objectMapper

      public RestClientBuilder objectMapper(com.fasterxml.jackson.databind.ObjectMapper mapper)
      Sets the Jackson ObjectMapper for JSON serialization and deserialization. If not set, a default ObjectMapper is used.
      Parameters:
      mapper - the object mapper, must not be null.
      Returns:
      this builder for chaining.
      Since:
      5.7

    • build

      public <T> T build(Class<T> iface)
      Scans the given interface for Jakarta REST annotations and creates a proxy that implements it by dispatching HTTP requests through the configured async client.
      Type Parameters:
      T - the interface type.
      Parameters:
      iface - the Jakarta REST annotated interface class.
      Returns:
      a proxy implementing the interface.
      Throws:
      IllegalArgumentException - if the class is not an interface.
      IllegalStateException - if no base URI or client has been set, or if the interface has no Jakarta REST annotated methods.
      RestResourceException - if the interface violates Jakarta REST contract.