io.lettuce.core.support.http

Interface HttpClient

All Superinterfaces:

AutoCloseable, Closeable

@Experimental
public interface HttpClient
extends Closeable

Interface for performing HTTP requests in a dependency-agnostic manner. This interface provides basic HTTP client functionality for health checks and other lightweight HTTP operations.

Implementations can be provided via HttpClientProvider SPI or by using the default Netty-based implementation. The client uses a shared Netty infrastructure (event loops) and supports connection reuse. Once a channel is initialized with specific SSL options and timeouts, it can be reused for multiple HTTP requests to the same host until the connection is closed, times out, or encounters an error.

Usage example:

 HttpClient client = HttpClientResources.shared();
 ConnectionConfig config = ConnectionConfig.builder().sslOptions(sslOptions).connectionTimeout(1000).readTimeout(1000)
         .build();

 try (HttpConnection conn = client.connect(URI.create("https://example.com"), config)) {
     Request request1 = Request.get("/api/endpoint1").build();
     Response response1 = conn.execute(request1);
     if (response1.getStatusCode() == 200) {
         String body = response1.getResponseBody(StandardCharsets.UTF_8);
         // Process response
     }

     Request request2 = Request.get("/api/endpoint2").queryParam("filter", "active").build();
     Response response2 = conn.execute(request2);
     // Multiple requests reuse the same connection
 }
 

Since:

7.4

Author:

Ivo Gaydazhiev

See Also:

HttpClientProvider

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	HttpClient.ConnectionConfig Per-connection configuration for HTTP connections.
static interface	HttpClient.HttpConnection Represents an HTTP connection that can be reused for multiple requests.
static class	HttpClient.Method HTTP request method.
static interface	HttpClient.Request Represents an HTTP request with method, path, query parameters, headers, and optional body.
static interface	HttpClient.Response Represents an HTTP response with status code, headers, and body.

Method Summary

Modifier and Type	Method and Description
HttpClient.HttpConnection	connect(URI uri, HttpClient.ConnectionConfig connectionConfig) Establishes an HTTP connection to the specified URI with the given configuration.
CompletableFuture<HttpClient.HttpConnection>	connectAsync(URI uri, HttpClient.ConnectionConfig connectionConfig) Asynchronously establishes an HTTP connection to the specified URI with the given configuration.
void	shutdown() Shutdown this client.
void	shutdown(long quietPeriod, long timeout, TimeUnit timeUnit) Shutdown this client.

Methods inherited from interface java.io.Closeable

close

Method Detail

connect

HttpClient.HttpConnection connect(URI uri,
                                  HttpClient.ConnectionConfig connectionConfig)
                           throws IOException

Establishes an HTTP connection to the specified URI with the given configuration. The returned connection can be reused for multiple HTTP requests to the same host. The connection uses HTTP/1.1 keep-alive to maintain the underlying channel.

The SSL options and timeouts are configured once during connection establishment and apply to all requests made through this connection.

Parameters:

uri - the URI to connect to (scheme, host, and port are used), must not be null.

connectionConfig - the connection-specific configuration (SSL, timeouts), must not be null.

Returns:

an HttpClient.HttpConnection that can be used to perform multiple requests.

Throws:

IOException - if an I/O error occurs during connection establishment.

connectAsync

CompletableFuture<HttpClient.HttpConnection> connectAsync(URI uri,
                                                          HttpClient.ConnectionConfig connectionConfig)

Asynchronously establishes an HTTP connection to the specified URI with the given configuration.

Parameters:

uri - the URI to connect to (scheme, host, and port are used), must not be null.

connectionConfig - the connection-specific configuration (SSL, timeouts), must not be null.

Returns:

a CompletableFuture that will be completed with an HttpClient.HttpConnection.

shutdown

void shutdown()

Shutdown this client. The shutdown is executed without quiet time and a timeout of 2 TimeUnit.SECONDS.

See Also:

shutdown(long, long, TimeUnit)

shutdown

void shutdown(long quietPeriod,
              long timeout,
              TimeUnit timeUnit)

Shutdown this client.

Parameters:

quietPeriod - the quiet period to allow the executor gracefully shut down.

timeout - the maximum amount of time to wait until the backing executor is shutdown regardless if a task was submitted during the quiet period.

timeUnit - the unit of quietPeriod and timeout.