Apache HttpClient

https://github.com/apache/httpcomponents-client
Admin
Apache HttpComponents Client is a powerful and flexible Java-based HTTP client that supports all...
Tokens:828,005
Snippets:4,662
Trust Score:9.1
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### start()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClient.md

Starts the client's I/O reactor. Must be called before any execute method.

```APIDOC
## start()

### Description
Starts the asynchronous client's I/O reactor. Must be called before any execute method.

### Method
start

### Signature
public abstract void start()

### Parameters
None

### Returns
void

### Remarks
- Must be called before execute(...) methods.
- Lifecycle contract: start() must be called before execute(...).
```

--------------------------------

### Minimal Async Client Usage Examples

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClient.md

Code examples for using the minimal async HTTP clients and their execution methods.

```APIDOC
## [SDK] MinimalHttpAsyncClient

### Description
Minimal HTTP/1.1 (+ optional HTTP/2 via config) asynchronous client with minimal processing.

### Class
`org.apache.hc.client5.http.impl.async.MinimalHttpAsyncClient`

### Extends
`AbstractMinimalHttpAsyncClientBase`

### Usage
```java
// Instantiate via HttpAsyncClients or builder
```

```

```APIDOC
## [SDK] MinimalH2AsyncClient

### Description
HTTP/2-only minimal asynchronous client.

### Class
`org.apache.hc.client5.http.impl.async.MinimalH2AsyncClient`

### Usage
```java
// Instantiate via HttpAsyncClients or builder
```

```

```APIDOC
## [SDK] HttpAsyncClients.createDefault()

### Description
Creates a default `CloseableHttpAsyncClient` instance.

### Method
`static CloseableHttpAsyncClient createDefault()`

### Example
```java
import org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient;
import org.apache.hc.client5.http.impl.async.HttpAsyncClients;

try (final CloseableHttpAsyncClient client = HttpAsyncClients.createDefault()) {
    client.start();
    // use client
}
```

```

```APIDOC
## [SDK] CloseableHttpAsyncClient.execute(SimpleHttpRequest, callback)

### Description
Executes a simple HTTP request asynchronously and returns a `Future<SimpleHttpResponse>`.

### Method
`Future<SimpleHttpResponse> execute(SimpleHttpRequest request, FutureCallback<SimpleHttpResponse> callback)`

### Parameters
- **request** (SimpleHttpRequest) - Required - The request to execute.
- **callback** (FutureCallback<SimpleHttpResponse>) - Optional - Callback for completion or failure.

### Example
```java
import org.apache.hc.client5.http.async.methods.SimpleHttpRequest;
import org.apache.hc.client5.http.async.methods.SimpleHttpResponse;
import org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient;

client.start();
final SimpleHttpResponse response = client.execute(
        SimpleHttpRequest.create("GET", "https://example.com/"), null)
        .get(10, TimeUnit.SECONDS);
System.out.println(response.getCode());
```

```

```APIDOC
## [SDK] CloseableHttpAsyncClient.execute(AsyncRequestProducer, AsyncResponseConsumer, callback)

### Description
Executes an asynchronous request with a producer, consumer, and callback for full-duplex exchange.

### Method
`Future<HttpResponse> execute(AsyncRequestProducer requestProducer, AsyncResponseConsumer<T> responseConsumer, FutureCallback<T> callback)`

### Parameters
- **requestProducer** (AsyncRequestProducer) - Required - Produces the request.
- **responseConsumer** (AsyncResponseConsumer) - Required - Consumes the response.
- **callback** (FutureCallback) - Required - Callback for completion, failure, or cancellation.

### Example
```java
client.start();
final Future<HttpResponse> future = client.execute(
        BasicRequestProducer.create(new HttpGet("https://example.com/")),
        BasicResponseConsumer.create(),
        new FutureCallback<HttpResponse>() {
            @Override public void completed(final HttpResponse r) { /* process */ }
            @Override public void failed(final Exception ex) {
                // e.g. ConnectTimeoutException, RequestFailedException
            }
            @Override public void cancelled() { }
        });
```

```

```APIDOC
## [SDK] Future.cancel(boolean)

### Description
Cancels a future to release exchange resources, especially on timeout or execution failure.

### Method
`boolean cancel(boolean mayInterruptIfRunning)`

### Example
```java
final Future<SimpleHttpResponse> f = client.execute(request, null);
try {
    return f.get(5, TimeUnit.SECONDS);
} catch (final TimeoutException | ExecutionException ex) {
    f.cancel(true); // release the exchange resources
    throw new IOException("exchange failed", ex);
}
```

```

--------------------------------

### Execute a simple GET via HttpAsyncClient

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/SimpleApi.md

Example of executing a simple GET request using the `HttpAsyncClient` and `SimpleHttpRequest`.

```APIDOC
## Execute a simple GET via `HttpAsyncClient`

```java
import org.apache.hc.client5.http.async.methods.SimpleHttpRequest;
import org.apache.hc.client5.http.async.methods.SimpleHttpResponse;
import org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient;
import org.apache.hc.client5.http.impl.async.HttpAsyncClients;

try (final CloseableHttpAsyncClient client = HttpAsyncClients.createDefault()) {
    client.start();
    final SimpleHttpRequest request = SimpleHttpRequest.create("GET", "https://example.com/");
    SimpleHttpResponse response = client.execute(request, null).get(10, TimeUnit.SECONDS);
    System.out.println(response.getCode() + " " + response.getBodyText());
}
```
```

--------------------------------

### Build and install JAR packages

Source: https://github.com/apache/httpcomponents-client/blob/master/BUILDING.txt

Builds the JAR packages and installs them to the local Maven repository. The resulting JARs are placed in the target folders of their respective modules.

```bash
mvn install
```

--------------------------------

### CloseableWebSocketClient.start()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/WebSocket.md

Starts the WebSocket client, preparing it to establish connections. This must be called before attempting to connect.

```APIDOC
## CloseableWebSocketClient.start()

### Description
Starts the WebSocket client, preparing it to establish connections. This must be called before attempting to connect.

### Method
GET

### Endpoint
CloseableWebSocketClient.start()

### Parameters
None

### Request Example
```java
client.start();
```

### Response
#### Success Response (200)
- **void** - This method does not return a value.

#### Response Example
N/A
```

--------------------------------

### CloseableWebSocketClient.start()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/WebSocket.md

Starts the WebSocket client. Must be called before any connect method.

```APIDOC
## CloseableWebSocketClient.start()

### Description
Starts the WebSocket client. Must be called before any connect method.

### Method
start

### Signature
```java
public abstract void start();
```

### Parameters
None.

### Returns
void
```

--------------------------------

### Default client simple request/response with HttpAsyncClients.createDefault()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClient.md

Creates a default CloseableHttpAsyncClient, starts it, and executes a simple GET request with a 10-second timeout, printing the response code. Uses SimpleHttpRequest and SimpleHttpResponse from the async methods package.

```java
import org.apache.hc.client5.http.async.methods.SimpleHttpRequest;
import org.apache.hc.client5.http.async.methods.SimpleHttpResponse;
import org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient;
import org.apache.hc.client5.http.impl.async.HttpAsyncClients;

try (final CloseableHttpAsyncClient client = HttpAsyncClients.createDefault()) {
    client.start();
    final SimpleHttpResponse response = client.execute(
            SimpleHttpRequest.create("GET", "https://example.com/"), null)
            .get(10, TimeUnit.SECONDS);
    System.out.println(response.getCode());
}
```

--------------------------------

### Classic GET with auth using Executor

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Fluent.md

Creates an Executor with basic authentication for a host and performs a GET request with a 5-second connect timeout, returning the response content as a string.

```java
final Executor executor = Executor.newInstance()
        .auth(new HttpHost("example.com"), "user", "pass".toCharArray());

final Content content = executor.execute(
        Request.get("https://example.com/").connectTimeout(Timeout.ofSeconds(5)))
        .returnContent();
System.out.println(content.asString());
```

--------------------------------

### Manual producer/consumer pipeline

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/SimpleApi.md

Example of manually creating a producer/consumer pipeline for executing a request and consuming the response.

```APIDOC
## Manual producer/consumer pipeline

```java
final Future<SimpleHttpResponse> future = client.execute(
        SimpleRequestProducer.create(request),
        SimpleResponseConsumer.create(),
        null, null);
```
```

--------------------------------

### Execute simple GET via HttpAsyncClient

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/SimpleApi.md

Executes a simple GET request using HttpAsyncClient. The client is started, a SimpleHttpRequest is created, and the response is retrieved synchronously with a 10-second timeout.

```java
import org.apache.hc.client5.http.async.methods.SimpleHttpRequest;
import org.apache.hc.client5.http.async.methods.SimpleHttpResponse;
import org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient;
import org.apache.hc.client5.http.impl.async.HttpAsyncClients;

try (final CloseableHttpAsyncClient client = HttpAsyncClients.createDefault()) {
    client.start();
    final SimpleHttpRequest request = SimpleHttpRequest.create("GET", "https://example.com/");
    SimpleHttpResponse response = client.execute(request, null).get(10, TimeUnit.SECONDS);
    System.out.println(response.getCode() + " " + response.getBodyText());
}
```

--------------------------------

### Finite retries (error-handling example)

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Sse.md

Example of configuring a fixed backoff strategy with a maximum number of reconnects and handling stream closure and failure.

```APIDOC
## Finite retries (error-handling example)

### Description
Demonstrates how to set up an EventSourceConfig with a fixed backoff and a finite number of reconnects, and how to handle onFailure and onClosed events.

### Code Example
```java
final EventSourceConfig finite = EventSourceConfig.builder()
        .backoff(new FixedBackoffStrategy(2_000L))
        .maxReconnects(3)
        .build();

final EventSource source = exec.open(URI.create("https://example.com/events"), headers,
        new EventSourceListener() {
            @Override public void onEvent(final String id, final String type, final String data) { }
            @Override public void onFailure(final Throwable t, final boolean willReconnect) {
                if (!willReconnect) {
                    // maxReconnects exhausted or NoBackoffStrategy: give up
                    System.err.println("giving up: " + t);
                }
            }
            @Override public void onClosed() {
                System.out.println("stream closed");
            }
        }, finite);
```

```

--------------------------------

### Echo client with WebSocketClientBuilder

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/WebSocket.md

Echo client example using WebSocketClientBuilder and CloseableWebSocketClient. Enables permessage-deflate, sets close wait timeout, connects to ws://localhost:8080/echo, sends "hello", prints echoed text, and closes with NORMAL status. Waits 1 second for close handshake before try-with-resources exits.

```java
final WebSocketClientConfig cfg = WebSocketClientConfig.custom()
        .enablePerMessageDeflate(true)
        .setCloseWaitTimeout(Timeout.ofSeconds(2))
        .build();

try (final CloseableWebSocketClient client = WebSocketClientBuilder.create()
        .defaultConfig(cfg)
        .build()) {
    client.start();
    final WebSocket ws = client.connect(URI.create("ws://localhost:8080/echo"), new WebSocketListener() {
        @Override public void onOpen(final WebSocket ws) {
            ws.sendText("hello", true);
        }
        @Override public void onText(final CharBuffer text, final boolean last) {
            System.out.println("echo: " + text);
            ws.close(WebSocketCloseStatus.NORMAL.getCode(), "done");
        }
        @Override public void onClose(final int code, final String reason) {
            System.out.println("closed: " + code + " " + reason);
        }
        @Override public void onError(final Throwable ex) {
            System.err.println("ws error: " + ex);
        }
    }).get(5, TimeUnit.SECONDS);

    // wait for the close handshake before exiting the try-with-resources
    Thread.sleep(1000);
}
```

--------------------------------

### Build a JSON POST with SimpleRequestBuilder

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/SimpleApi.md

Example of building a JSON POST request with `SimpleRequestBuilder` and executing it asynchronously with a callback.

```APIDOC
## Build a JSON POST with `SimpleRequestBuilder`

```java
final SimpleHttpRequest req = SimpleRequestBuilder.post("https://api.example.com/items")
        .setBody("{\"name\":\"widget\"}", ContentType.APPLICATION_JSON)
        .setHeader("Authorization", "Bearer abc123")
        .build();

client.execute(req, new FutureCallback<>() {
    @Override public void completed(final SimpleHttpResponse response) {
        System.out.println(response.getCode() + " " + response.getBodyText());
    }
    @Override public void failed(final Exception ex) {
        System.err.println("Request failed: " + ex);   // e.g. ConnectTimeoutException
    }
    @Override public void cancelled() {
        System.out.println("cancelled");
    }
});
```
```

--------------------------------

### GET http://httpbin.org/get

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpClients.md

Basic usage of `CloseableHttpClient` with automatic resource management, executing a GET request and printing the status and response body.

```APIDOC
## [GET] http://httpbin.org/get

### Description
Performs a basic HTTP GET request using the default `CloseableHttpClient` with automatic resource management. The response is consumed within the lambda and the connection is released automatically.

### Method
GET

### Endpoint
http://httpbin.org/get

### Parameters
#### Query Parameters
None explicitly documented.

#### Request Body
None.

### Request Example
No explicit request body is provided; the request is a simple GET.

### Response
#### Success Response (200)
- **response.getCode()** (int) - HTTP status code.
- **response.getReasonPhrase()** (String) - Reason phrase associated with the status code.
- **response.getEntity()** (HttpEntity) - Response body entity, which can be converted to a string using `EntityUtils.toString()`.

#### Response Example
No explicit response body example is provided in the source.
```

--------------------------------

### SimpleHttpResponse Instance Methods

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/SimpleApi.md

Methods to set and get the response body, content type, and body as text or bytes.

```APIDOC
## SimpleHttpResponse Instance Methods

### Description
Provides methods to manipulate and retrieve the response body and content type.

### Methods
- `void setBody(SimpleBody body)` - Sets the response body using a SimpleBody object.
- `void setBody(byte[] bodyBytes, ContentType contentType)` - Sets the response body from a byte array with the given content type.
- `void setBody(String bodyText, ContentType contentType)` - Sets the response body from a string with the given content type.
- `SimpleBody getBody()` - Returns the response body as a SimpleBody object.
- `ContentType getContentType()` - Returns the content type of the response.
- `String getBodyText()` - Returns the response body as a string.
- `byte[] getBodyBytes()` - Returns the response body as a byte array.

### Parameters
- **body** (SimpleBody) - Required for setBody(SimpleBody) - The body to set.
- **bodyBytes** (byte[]) - Required for setBody(byte[], ContentType) - The body bytes.
- **bodyText** (String) - Required for setBody(String, ContentType) - The body text.
- **contentType** (ContentType) - Required for setBody with content type - The content type.

### Usage Example
```java
response.setBody("Hello", ContentType.TEXT_PLAIN);
String text = response.getBodyText();
```
```

--------------------------------

### Per-route limits + TLS 1.3 only

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/ConnectionPool.md

Example of setting per-route connection limits and configuring TLS 1.3 as the only supported protocol.

```APIDOC
## Per-route limits + TLS 1.3 only

### Description
Example of setting maximum total connections, default per-route limits, and a specific per-route limit for a host, along with a default TLS config that only supports TLS 1.3.

### Code Example
```java
connManager.setMaxTotal(100);
connManager.setDefaultMaxPerRoute(10);
connManager.setMaxPerRoute(new HttpRoute(new HttpHost("somehost", 80)), 20);
connManager.setDefaultTlsConfig(TlsConfig.custom()
        .setHandshakeTimeout(Timeout.ofSeconds(30))
        .setSupportedProtocols(TLS.V_1_3)
        .build());
```
```

--------------------------------

### Basic usage with automatic resource management

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpClients.md

Creates a default CloseableHttpClient and executes an HTTP GET request using try-with-resources for automatic resource management. The response is processed with a lambda that prints the status code and reason phrase, and consumes the entity.

```java
import org.apache.hc.client5.http.classic.methods.HttpGet;
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.core5.http.io.entity.EntityUtils;

try (final CloseableHttpClient httpclient = HttpClients.createDefault()) {
    final HttpGet httpget = new HttpGet("http://httpbin.org/get");
    httpclient.execute(httpget, response -> {
        System.out.println(response.getCode() + " " + response.getReasonPhrase());
        System.out.println(EntityUtils.toString(response.getEntity()));
        return null;
    });
}
```

--------------------------------

### GET https://expired.badssl.com/

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpClients.md

Example of error handling when executing a GET request, catching `IOException` for transport-level failures.

```APIDOC
## [GET] https://expired.badssl.com/

### Description
Demonstrates error handling when executing a GET request against a host with an expired SSL certificate. Transport-level failures are surfaced as `IOException` and can be caught to handle SSL handshake, connection timeout, or unknown host errors.

### Method
GET

### Endpoint
https://expired.badssl.com/

### Parameters
#### Path Parameters
None.

#### Query Parameters
None explicitly documented.

#### Request Body
None.

### Request Example
No explicit request body is provided.

### Response
#### Success Response (200)
- **response.getEntity()** (HttpEntity) - Response body entity, which is consumed using `EntityUtils.consume()`.

#### Error Response
- **IOException** - Thrown for transport-level failures, such as `SSLHandshakeException`, `ConnectTimeoutException`, or `UnknownHostException`.

#### Response Example
No explicit response body example is provided in the source.
```

--------------------------------

### Basic auth via builder

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Authentication.md

Shows how to set up default credentials for an HttpClient and execute a request with basic authentication.

```APIDOC
## [JAVA] Basic auth via builder

### Description
This example demonstrates how to configure a CloseableHttpClient with default credentials using the CredentialsProviderBuilder and execute a GET request with basic authentication.

### Code
```java
final CloseableHttpClient httpclient = HttpClients.custom()
        .setDefaultCredentialsProvider(CredentialsProviderBuilder.create()
                .add(new HttpHost("httpbin.org", 80), "user", "passwd".toCharArray())
                .build())
        .build();

httpclient.execute(new HttpGet("http://httpbin.org/basic-auth/user/passwd"), response -> {
    System.out.println(response.getCode()); // 200 when credentials are accepted
    EntityUtils.consume(response.getEntity());
    return null;
});
```
```

--------------------------------

### Preemptive auth (challenge is not required)

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Authentication.md

Shows how to configure preemptive basic authentication using ContextBuilder and execute a request with that context.

```APIDOC
## [JAVA] Preemptive auth (challenge is not required)

### Description
This example demonstrates how to configure an HttpClientContext to send basic authentication credentials preemptively, without waiting for a challenge from the server.

### Code
```java
final HttpClientContext context = ContextBuilder.create()
        .preemptiveBasicAuth(new HttpHost("https", "example.com"),
                new UsernamePasswordCredentials("user", "pass".toCharArray()))
        .build();
httpclient.execute(new HttpGet("https://example.com/private"), context, handler);
```
```

--------------------------------

### Async completable GET with Async

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Fluent.md

Performs an asynchronous GET request using Async and CompletableFuture, printing the content on success and the exception on failure.

```java
final CompletableFuture<Content> f = Async.newInstance()
        .executeAsync(Request.get("https://example.com/"));
f.thenAccept(c -> System.out.println(c.asString()))
 .exceptionally(ex -> { System.err.println(ex); return null; });
```

--------------------------------

### ContextBuilder.preemptiveBasicAuth()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpClientContext.md

Configures preemptive basic authentication for a given host with the provided credentials.

```APIDOC
## ContextBuilder.preemptiveBasicAuth()

### Description
Configures preemptive basic authentication for a given host with the provided credentials.

### Method
Instance method

### Signature
`public ContextBuilder preemptiveBasicAuth(final HttpHost host, final UsernamePasswordCredentials credentials)`

### Parameters
- **host** (HttpHost) - Required - The target host for preemptive auth.
- **credentials** (UsernamePasswordCredentials) - Required - The credentials to use.

### Returns
This ContextBuilder instance for chaining.
```

--------------------------------

### HttpAsyncClients.createMinimal(ThreadFactory, ThreadFactory, H2Config, Http1Config, CharCodingConfig, DnsResolver)

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClient.md

Creates a minimal asynchronous HTTP client with full configuration options.

```APIDOC
## HttpAsyncClients.createMinimal(ThreadFactory, ThreadFactory, H2Config, Http1Config, CharCodingConfig, DnsResolver)

### Description
Creates a `MinimalHttpAsyncClient` with the provided thread factories, protocol configurations, character coding, and DNS resolver. The minimal client does not support redirects, retries, or authentication.

### Method
Factory method

### Endpoint
N/A (Java factory method)

### Parameters
- `mainThreadFactory` (ThreadFactory) - Required - Factory for the main thread.
- `dispatchThreadFactory` (ThreadFactory) - Required - Factory for the dispatch thread.
- `h2Config` (H2Config) - Required - HTTP/2 configuration.
- `http1Config` (Http1Config) - Required - HTTP/1.1 configuration.
- `charCodingConfig` (CharCodingConfig) - Required - Character coding configuration.
- `dnsResolver` (DnsResolver) - Required - DNS resolver.

### Returns
- `MinimalHttpAsyncClient` - A minimal asynchronous HTTP client.

### Example
```java
MinimalHttpAsyncClient client = HttpAsyncClients.createMinimal(
    new DefaultThreadFactory("httpclient-main", true),
    new DefaultThreadFactory("httpclient-dispatch", true),
    H2Config.DEFAULT,
    Http1Config.DEFAULT,
    CharCodingConfig.DEFAULT,
    SystemDefaultDnsResolver.INSTANCE
);
```
```

--------------------------------

### HttpAsyncClients.createMinimal()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClient.md

Creates a minimal asynchronous HTTP client with default configurations.

```APIDOC
## HttpAsyncClients.createMinimal()

### Description
Creates a `MinimalHttpAsyncClient` with default configurations for HTTP/1.1 and HTTP/2.

### Method
Factory method

### Endpoint
N/A (Java factory method)

### Parameters
None

### Returns
- `MinimalHttpAsyncClient` - A minimal asynchronous HTTP client.

### Example
```java
MinimalHttpAsyncClient client = HttpAsyncClients.createMinimal();
```
```

--------------------------------

### Basic GET with CloseableHttpClient

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/ClassicRequests.md

Performs a simple GET request using the classic HttpClient API. The response body is read as a string via EntityUtils.toString. The try-with-resources block ensures the client is closed automatically.

```java
import org.apache.hc.client5.http.classic.methods.HttpGet;
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.core5.http.io.entity.EntityUtils;

try (final CloseableHttpClient httpclient = HttpClients.createDefault()) {
    final HttpGet httpget = new HttpGet("http://example.com/");
    String body = httpclient.execute(httpget, response ->
            EntityUtils.toString(response.getEntity()));
}
```

--------------------------------

### Create JKS store with Test CA cert using keytool

Source: https://github.com/apache/httpcomponents-client/blob/master/httpclient5-testing/src/test/resources/docker/BUILDING.txt

Imports the test CA certificate into a Java keystore with alias 'test-ca' and store password 'nopassword'. Run from the project root.

```bash
keytool -import -trustcacerts -alias test-ca -file test-CA/ca-cert.pem -keystore httpcore5-testing/src/test/resources/test-ca.jks -storepass nopassword
```

--------------------------------

### HttpAsyncClients.createSystem() (Deprecated)

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClient.md

Deprecated method that behaves identically to createDefault().

```APIDOC
## HttpAsyncClients.createSystem() (Deprecated)

### Description
Deprecated. Creates a default asynchronous HTTP client, equivalent to `createDefault()`.

### Method
Factory method

### Endpoint
N/A (Java factory method)

### Parameters
None

### Returns
- `CloseableHttpAsyncClient` - A default asynchronous HTTP client.

### Example
```java
CloseableHttpAsyncClient client = HttpAsyncClients.createSystem();
```
```

--------------------------------

### Async.newInstance()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Fluent.md

Creates a new Async instance.

```APIDOC
## Async.newInstance()

### Description
Creates a new Async instance.

### Method
newInstance

### Signature
`public static Async newInstance()`

### Parameters
None

### Returns
Async - A new Async instance.
```

--------------------------------

### Run tests with Maven

Source: https://github.com/apache/httpcomponents-client/blob/master/BUILDING.txt

Compiles and runs the test suite for the project. Execute from the project root.

```bash
mvn test
```

--------------------------------

### Tuned blocking pool

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/ConnectionPool.md

Example of creating a PoolingHttpClientConnectionManager with custom settings for max connections, pool policies, and timeouts.

```APIDOC
## Tuned blocking pool

### Description
Example of building a `PoolingHttpClientConnectionManager` with a builder, setting maximum total and per-route connections, pool concurrency policy, connection pool policy, and default connection config with timeouts.

### Code Example
```java
final PoolingHttpClientConnectionManager connManager = PoolingHttpClientConnectionManagerBuilder.create()
        .setMaxConnTotal(100)
        .setMaxConnPerRoute(10)
        .setPoolConcurrencyPolicy(PoolConcurrencyPolicy.STRICT)
        .setConnPoolPolicy(PoolReusePolicy.LIFO)
        .setDefaultConnectionConfig(ConnectionConfig.custom()
                .setConnectTimeout(Timeout.ofSeconds(30))
                .setSocketTimeout(Timeout.ofSeconds(30))
                .setValidateAfterInactivity(TimeValue.ofSeconds(10))
                .setTimeToLive(TimeValue.ofHours(1))
                .build())
        .build();

try (final CloseableHttpClient httpclient = HttpClients.custom()
        .setConnectionManager(connManager)
        .build()) { ... }
```
```

--------------------------------

### WebSocketClient.connect(URI, WebSocketListener, WebSocketClientConfig, HttpContext)

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/WebSocket.md

Establishes a WebSocket connection to the given URI. The returned CompletableFuture completes when the opening handshake finishes, or exceptionally on failure.

```APIDOC
## WebSocketClient.connect(URI, WebSocketListener, WebSocketClientConfig, HttpContext)

### Description
Establishes a WebSocket connection to the given URI. The returned CompletableFuture completes when the opening handshake finishes, or exceptionally on failure.

### Method
connect

### Signature
```java
CompletableFuture<WebSocket> connect(
        URI uri,
        WebSocketListener listener,
        WebSocketClientConfig cfg,
        HttpContext context);
```

### Parameters
- **uri** (URI) - Required - The WebSocket endpoint URI.
- **listener** (WebSocketListener) - Required - Listener for WebSocket events.
- **cfg** (WebSocketClientConfig) - Optional - Configuration for the WebSocket client.
- **context** (HttpContext) - Optional - HTTP context for the connection.

### Returns
- **CompletableFuture<WebSocket>** - Completes when the opening handshake finishes; completes exceptionally on failure (e.g., WebSocketException, IOException).
```

--------------------------------

### GET http://httpbin.org/get (executeOpen)

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpClients.md

Usage of `executeOpen` to manually manage the response lifecycle, holding the connection until the response is closed.

```APIDOC
## [GET] http://httpbin.org/get (executeOpen)

### Description
Executes a GET request while keeping the response open manually, allowing the connection to be held until the response is closed. This is useful when the response entity needs to be processed outside the execute callback.

### Method
GET

### Endpoint
http://httpbin.org/get

### Parameters
#### Path Parameters
None.

#### Query Parameters
None explicitly documented.

#### Request Body
None.

### Request Example
No explicit request body is provided.

### Response
#### Success Response (200)
- **response.getEntity()** (HttpEntity) - Response body entity, which can be converted to a string using `EntityUtils.toString()`.

#### Response Example
No explicit response body example is provided in the source.
```

--------------------------------

### initiateShutdown()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClient.md

Begins graceful shutdown of the client's I/O reactor.

```APIDOC
## initiateShutdown()

### Description
Begins graceful shutdown of the client's I/O reactor.

### Method
initiateShutdown

### Signature
public abstract void initiateShutdown()

### Parameters
None

### Returns
void

### Remarks
- Lifecycle contract: initiateShutdown() begins graceful shutdown.
```

--------------------------------

### Streaming with retry backoff

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Sse.md

Example of opening an SSE stream with exponential jitter backoff, unlimited reconnects, and a custom parser strategy.

```APIDOC
## Streaming with retry backoff

### Description
Demonstrates how to configure an EventSourceConfig with exponential jitter backoff and unlimited reconnects, build an SseExecutor, and open an EventSource to stream events.

### Code Example
```java
final EventSourceConfig cfg = EventSourceConfig.builder()
        .backoff(new ExponentialJitterBackoff(500L, 30_000L, 2.0, 250L))
        .maxReconnects(-1) // unlimited
        .build();

final SseExecutor exec = SseExecutor.custom()
        .setEventSourceConfig(cfg)
        .addDefaultHeader("Accept", "text/event-stream")
        .setParserStrategy(SseParser.BYTE)
        .build();

final EventSource source = exec.open(
        URI.create("https://stream.wikimedia.org/v2/stream/recentchange"),
        new EventSourceListener() {
            @Override public void onEvent(final String id, final String type, final String data) {
                System.out.println("[" + type + "] " + data);
            }
            @Override public void onFailure(final Throwable t, final boolean willReconnect) {
                System.err.println("stream error, reconnect=" + willReconnect + ": " + t);
            }
        });
// source.start() is implicit; cancel when done:
// source.cancel();
```

```

--------------------------------

### HttpAsyncClients.createHttp2Minimal()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClient.md

Creates a minimal HTTP/2-only asynchronous client with default configurations.

```APIDOC
## HttpAsyncClients.createHttp2Minimal()

### Description
Creates a `MinimalH2AsyncClient` (HTTP/2 only) with default configurations.

### Method
Factory method

### Endpoint
N/A (Java factory method)

### Parameters
None

### Returns
- `MinimalH2AsyncClient` - A minimal HTTP/2-only asynchronous client.

### Example
```java
MinimalH2AsyncClient client = HttpAsyncClients.createHttp2Minimal();
```
```

--------------------------------

### Pool exhaustion (error handling)

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/ConnectionPool.md

Example of handling pool exhaustion with a strict concurrency policy and a tiny pool, where lease timeouts surface as ConnectionRequestTimeoutException.

```APIDOC
## Pool exhaustion (error handling)

### Description
Example of configuring a connection pool with strict concurrency and a maximum of one connection per route, causing concurrent requests to wait for a lease. If a lease timeout is set via `RequestConfig.setConnectionRequestTimeout(...)`, a `ConnectionRequestTimeoutException` (an `IOException` subclass) is thrown.

### Code Example
```java
final PoolingHttpClientConnectionManager cm = PoolingHttpClientConnectionManagerBuilder.create()
        .setMaxConnTotal(1)
        .setMaxConnPerRoute(1)
        .setPoolConcurrencyPolicy(PoolConcurrencyPolicy.STRICT)
        .build();
```
```

--------------------------------

### Request configuration methods

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Fluent.md

Methods to configure version, expect-continue, user agent, timeouts, and proxy.

```APIDOC
## Request configuration methods

### Description
Methods to configure version, expect-continue, user agent, timeouts, and proxy.

### Methods
- `public Request version(final HttpVersion version)`
- `public Request useExpectContinue()`
- `public Request userAgent(final String agent)`
- `public Request connectTimeout(final Timeout timeout)`
- `public Request responseTimeout(final Timeout timeout)`
- `public Request viaProxy(final HttpHost proxy)`
- `public Request viaProxy(final String proxy)`

### Parameters
- `version` (HttpVersion) - Required - The HTTP version.
- `agent` (String) - Required - The user agent string.
- `timeout` (Timeout) - Required - The timeout value.
- `proxy` (HttpHost) - Required - The proxy host.
- `proxy` (String) - Required - The proxy as a string.

### Returns
- `Request` - This Request instance for chaining.
```

--------------------------------

### Error handling: malformed challenge

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Authentication.md

Catches MalformedChallengeException when processing an invalid challenge. The example uses a garbage challenge value to trigger the exception and prints the error message.

```java
try {
    authScheme.processChallenge(new AuthChallenge(ChallengeType.TARGET, "Digest",
            "garbage-value-without-params"), HttpClientContext.create());
} catch (final MalformedChallengeException ex) {
    System.err.println("Server sent an unparseable challenge: " + ex.getMessage());
}
```

--------------------------------

### WebSocketClientConfig.Builder.build()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/WebSocket.md

Builds the WebSocketClientConfig instance with the configured settings.

```APIDOC
## WebSocketClientConfig.Builder.build()

### Description
Builds the WebSocketClientConfig instance with the configured settings.

### Method
GET

### Endpoint
WebSocketClientConfig.Builder.build()

### Parameters
None

### Request Example
```java
.build()
```

### Response
#### Success Response (200)
- **WebSocketClientConfig** - The configured WebSocket client configuration.

#### Response Example
N/A
```

--------------------------------

### Memory-bound caching client

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Cache.md

Creates a memory-bound caching HTTP client using CachingHttpClients.createMemoryBound() and executes a GET request with an HttpCacheContext. The response is consumed via EntityUtils.consume() inside the response handler.

```java
final CloseableHttpClient httpclient = CachingHttpClients.createMemoryBound();
final HttpCacheContext context = HttpCacheContext.create();

httpclient.execute(new HttpGet("https://example.com/"), context, response -> {
    EntityUtils.consume(response.getEntity());
});
```

--------------------------------

### Enable tracing/metering on a classic client

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Observation.md

Configures an ObservationRegistry and ObservingOptions, then enables HttpClientObservationSupport on a builder before building the client. The enable() call must be applied before build() because it mutates the builder's exec chain and connection-manager wiring.

```java
import io.micrometer.core.instrument.simple.SimpleMeterRegistry;
import io.micrometer.observation.ObservationRegistry;

final ObservationRegistry obsReg = ObservationRegistry.create();
final ObservingOptions opts = ObservingOptions.builder()
        .metrics(ObservingOptions.allMetricSets())
        .tagLevel(ObservingOptions.TagLevel.EXTENDED)
        .build();

final HttpClientBuilder builder = HttpClients.custom()
        .setConnectionManager(PoolingHttpClientConnectionManagerBuilder.create()
                .setMaxConnTotal(50)
                .build());
HttpClientObservationSupport.enable(builder, obsReg, opts,
        MetricConfig.builder().prefix("http.client").percentiles(0.5, 0.99).build());
final CloseableHttpClient httpclient = builder.build();
```

--------------------------------

### Generate test keystore with self-signed key protected with key password

Source: https://github.com/apache/httpcomponents-client/blob/master/httpclient5-testing/src/test/resources/test-ssl.txt

Generates a test keystore with a self-signed key that is protected with a separate key password. The keystore uses the store password 'nopassword' and the key password 'password', with RSA 2048-bit encryption, an alias of 'simple-http-server', a validity of 100000 days, and a subject distinguished name for localhost. The SAN extension is set to DNS:localhost.

```shell
keytool -genkey \
  -keystore test-keypasswd.keystore -storepass nopassword \
  -keyalg RSA -keysize 2048 -keypass password \
  -alias simple-http-server \
  -validity 100000 \
  -dname "CN=localhost, OU=Apache HttpComponents, O=Apache Software Foundation" \
  -ext SAN="DNS:localhost"
```

--------------------------------

### Form class API

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Fluent.md

Constructs URL-encoded form data as a list of name/value pairs. Use `form()` to start, then chain `add(name, value)` calls before passing the result to a request body.

```java
public class Form {
    public static Form form();
    public Form add(final String name, final String value);
    public List<NameValuePair> toList();
}
```

--------------------------------

### Basic auth via builder

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Authentication.md

Sets default credentials via CredentialsProviderBuilder and executes a GET request. The response code 200 indicates accepted credentials; the entity is consumed to release the connection.

```java
final CloseableHttpClient httpclient = HttpClients.custom()
        .setDefaultCredentialsProvider(CredentialsProviderBuilder.create()
                .add(new HttpHost("httpbin.org", 80), "user", "passwd".toCharArray())
                .build())
        .build();

httpclient.execute(new HttpGet("http://httpbin.org/basic-auth/user/passwd"), response -> {
    System.out.println(response.getCode()); // 200 when credentials are accepted
    EntityUtils.consume(response.getEntity());
    return null;
});
```

--------------------------------

### BasicHttpRequests factory method signatures

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/SimpleApi.md

Overloads for each HTTP verb (get, delete, head, options, patch, post, put, trace, query) and generic create variants, mirroring ClassicHttpRequests for the low-level BasicHttpRequest class.

```java
public static BasicHttpRequest get(final String uri);
public static BasicHttpRequest get(final URI uri);
public static BasicHttpRequest get(final HttpHost host, final String path);
// ... delete, head, options, patch, post, put, trace, query
public static BasicHttpRequest create(final Method method, final String uri);
public static BasicHttpRequest create(final Method method, final URI uri);
public static BasicHttpRequest create(final Method method, final HttpHost host, final String path);
```

--------------------------------

### HTTP/2 client with multiplexing pools

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClientBuilder.md

Builds a custom async HTTP/2 client with push enabled, max concurrent streams set to 100, 4 I/O threads, and a 30-second response timeout. Call client.start() to begin processing.

```java
final CloseableHttpAsyncClient client = HttpAsyncClients.customHttp2()
        .setH2Config(H2Config.custom()
                .setPushEnabled(true)
                .setMaxConcurrentStreams(100)
                .build())
        .setIOReactorConfig(IOReactorConfig.custom()
                .setIoThreadCount(4)
                .build())
        .setDefaultRequestConfig(RequestConfig.custom()
                .setResponseTimeout(Timeout.ofSeconds(30))
                .build())
        .build();
client.start();
```

```java
try (final CloseableHttpAsyncClient client = HttpAsyncClients.custom()
        .setVersionPolicy(HttpVersionPolicy.FORCE_HTTP_2)
        .build()) {
    client.start();
    final SimpleHttpResponse r = client.execute(
            SimpleRequestBuilder.get("https://api.example.com/health").build(), null)
            .get(5, TimeUnit.SECONDS);
} catch (final ExecutionException ex) {
    // FORCE_HTTP_2 against an HTTP/1.1-only server fails here
    // (ProtocolException / UnsupportedSchemeException style failure wrapped in the future)
}
```

--------------------------------

### Error handling: hostname verification failure

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/Tls.md

Executes a GET request to https://wrong.host.badssl.com/ and catches SSLException to handle hostname verification failures. The comment notes that SSLPeerUnverifiedException indicates the hostname in the certificate didn't match.

```java
try {
    httpclient.execute(new HttpGet("https://wrong.host.badssl.com/"), response -> {
        EntityUtils.consume(response.getEntity());
        return null;
    });
} catch (final SSLException ex) {
    // SSLPeerUnverifiedException: hostname in certificate didn't match
    System.err.println("TLS verification failed: " + ex.getMessage());
}
```

--------------------------------

### HttpAsyncClients.createMinimal(H2Config, Http1Config)

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClient.md

Creates a minimal asynchronous HTTP client with HTTP/2 and HTTP/1.1 configurations.

```APIDOC
## HttpAsyncClients.createMinimal(H2Config, Http1Config)

### Description
Creates a `MinimalHttpAsyncClient` with the provided HTTP/2 and HTTP/1.1 configurations. Uses default thread factories and character coding.

### Method
Factory method

### Endpoint
N/A (Java factory method)

### Parameters
- `h2Config` (H2Config) - Required - HTTP/2 configuration.
- `h1Config` (Http1Config) - Required - HTTP/1.1 configuration.

### Returns
- `MinimalHttpAsyncClient` - A minimal asynchronous HTTP client.

### Example
```java
MinimalHttpAsyncClient client = HttpAsyncClients.createMinimal(
    H2Config.DEFAULT,
    Http1Config.DEFAULT
);
```
```

--------------------------------

### CloseableWebSocketClient abstract class

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/WebSocket.md

Abstract base class for WebSocket clients. Provides lifecycle methods (start, initiateShutdown, awaitShutdown) and overloaded connect methods. The connect(uri, listener) overload uses default configuration and HttpCoreContext.create().

```java
@Contract(threading = ThreadingBehavior.STATELESS)
public abstract class CloseableWebSocketClient implements WebSocketClient, ModalCloseable {
    public abstract void start();
    public abstract IOReactorStatus getStatus();
    public abstract void awaitShutdown(TimeValue waitTime) throws InterruptedException;
    public abstract void initiateShutdown();

    public final CompletableFuture<WebSocket> connect(final URI uri, final WebSocketListener listener);
    public final CompletableFuture<WebSocket> connect(final URI uri, final WebSocketListener listener,
            final WebSocketClientConfig cfg);
    public final CompletableFuture<WebSocket> connect(final URI uri, final WebSocketListener listener,
            final WebSocketClientConfig cfg, final HttpContext context);
}
```

--------------------------------

### HttpAsyncClients.createHttp2Minimal(ThreadFactory, ThreadFactory, H2Config, CharCodingConfig, DnsResolver)

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpAsyncClient.md

Creates a minimal HTTP/2-only asynchronous client with full configuration options.

```APIDOC
## HttpAsyncClients.createHttp2Minimal(ThreadFactory, ThreadFactory, H2Config, CharCodingConfig, DnsResolver)

### Description
Creates a `MinimalH2AsyncClient` (HTTP/2 only) with the provided thread factories, HTTP/2 configuration, character coding, and DNS resolver.

### Method
Factory method

### Endpoint
N/A (Java factory method)

### Parameters
- `mainThreadFactory` (ThreadFactory) - Required - Factory for the main thread.
- `dispatchThreadFactory` (ThreadFactory) - Required - Factory for the dispatch thread.
- `h2Config` (H2Config) - Required - HTTP/2 configuration.
- `charCodingConfig` (CharCodingConfig) - Required - Character coding configuration.
- `dnsResolver` (DnsResolver) - Required - DNS resolver.

### Returns
- `MinimalH2AsyncClient` - A minimal HTTP/2-only asynchronous client.

### Example
```java
MinimalH2AsyncClient client = HttpAsyncClients.createHttp2Minimal(
    new DefaultThreadFactory("httpclient-main", true),
    new DefaultThreadFactory("httpclient-dispatch", true),
    H2Config.DEFAULT,
    CharCodingConfig.DEFAULT,
    SystemDefaultDnsResolver.INSTANCE
);
```
```

--------------------------------

### ContextBuilder.preemptiveAuth()

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/HttpClientContext.md

Configures preemptive authentication for a given host and auth scheme, seeding the context with an AuthExchange.

```APIDOC
## ContextBuilder.preemptiveAuth()

### Description
Configures preemptive authentication for a given host and auth scheme, seeding the context with an AuthExchange.

### Method
Instance method

### Signature
`public ContextBuilder preemptiveAuth(final HttpHost host, final AuthScheme authScheme)`

### Parameters
- **host** (HttpHost) - Required - The target host for preemptive auth.
- **authScheme** (AuthScheme) - Required - The auth scheme to use.

### Returns
This ContextBuilder instance for chaining.
```

--------------------------------

### Generate test keystore with self-signed key

Source: https://github.com/apache/httpcomponents-client/blob/master/httpclient5-testing/src/test/resources/test-ssl.txt

Generates a test keystore with a self-signed key using keytool. The keystore is protected with the store password 'nopassword' and the key is created with RSA 2048-bit encryption, an alias of 'simple-http-server', a validity of 100000 days, and a subject distinguished name for localhost. The SAN extension is set to DNS:localhost.

```shell
keytool -genkey \
  -keystore test.keystore -storepass nopassword \
  -keyalg RSA -keysize 2048 \
  -alias simple-http-server \
  -validity 100000 \
  -dname "CN=localhost, OU=Apache HttpComponents, O=Apache Software Foundation" \
  -ext SAN="DNS:localhost"
```

--------------------------------

### Asynchronous request fan-out with FutureRequestExecutionService and metrics

Source: https://github.com/apache/httpcomponents-client/blob/master/_autodocs/api-reference/ProxyAndFuture.md

Executes an asynchronous HTTP GET with FutureRequestExecutionService, using a caller-provided ExecutorService. The returned FutureTask follows FutureTask semantics; metrics() reports request count. The caller must shut down the executor after closing the service.

```java
final ExecutorService executor = Executors.newFixedThreadPool(4);
final FutureRequestExecutionService service =
        new FutureRequestExecutionService(httpClient, executor);

final FutureTask<String> task = service.execute(
        new HttpGet("https://example.com/"),
        HttpClientContext.create(),
        new BasicHttpClientResponseHandler(),
        new FutureCallback<>() {
            @Override public void completed(final String result) { }
            @Override public void failed(final Exception ex) { }
            @Override public void cancelled() { }
        });

String body = task.get(10, TimeUnit.SECONDS);   // FutureTask semantics

System.out.println("requests: " + service.metrics().getRequestCount());
service.close();          // stop the service
executor.shutdown();      // the caller owns the executor
```
Tokens:
Raw