HttpClient (Java SE 26 & JDK 26)
Description: declaration: module: java.net.http, package: java.net.http, class: HttpClient
Keywords: java.net.http.HttpClient class

# Class HttpClient

java.lang.Object
java.net.http.HttpClient

All Implemented Interfaces:
  `AutoCloseable`

public abstract class HttpClient extends Object implements AutoCloseable
An HTTP Client.

An `HttpClient` can be used to send requests and retrieve their responses. An `HttpClient` is created through a `builder`. The `newBuilder` method returns a builder that creates instances of the default `HttpClient` implementation. The builder can be used to configure per-client state, like: the preferred protocol version ( HTTP/1.1, HTTP/2 or HTTP/3 ), whether to follow redirects, a proxy, an authenticator, etc. Once built, an `HttpClient` is immutable, and can be used to send multiple requests.

An `HttpClient` provides configuration information, and resource sharing, for all requests sent through it. An `HttpClient` instance typically manages its own pools of connections, which it may then reuse as and when necessary. Connection pools are typically not shared between `HttpClient` instances. Creating a new client for each operation, though possible, will usually prevent reusing such connections.

A `BodyHandler` must be supplied for each `HttpRequest` sent. The `BodyHandler` determines how to handle the response body, if any. Once an `HttpResponse` is received, the headers, response code, and body (typically) are available. Whether the response body bytes have been read or not depends on the type, `T`, of the response body.

Requests can be sent either synchronously or asynchronously:

- `send(HttpRequest, BodyHandler)` blocks until the request has been sent and the response has been received.
- `sendAsync(HttpRequest, BodyHandler)` sends the request and receives the response asynchronously. The `sendAsync` method returns immediately with a `CompletableFuture`<`HttpResponse`>. The `CompletableFuture` completes when the response becomes available. The returned `CompletableFuture` can be combined in different ways to declare dependencies among several asynchronous tasks.

Synchronous Example

    HttpClient client = HttpClient.newBuilder()
         .version(Version.HTTP_1_1)
         .followRedirects(Redirect.NORMAL)
         .connectTimeout(Duration.ofSeconds(20))
         .proxy(ProxySelector.of(new InetSocketAddress("proxy.example.com", 80)))
         .authenticator(Authenticator.getDefault())
         .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://foo.com/"))
        .build();
    HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());

Asynchronous Example

    HttpRequest request = HttpRequest.newBuilder()
         .uri(URI.create("https://foo.com/"))
         .timeout(Duration.ofMinutes(2))
         .header("Content-Type", "application/json")
         .POST(BodyPublishers.ofFile(Paths.get("file.json")))
         .build();
    client.sendAsync(request, BodyHandlers.ofString())
         .thenApply(HttpResponse::body)
         .thenAccept(System.out::println);

API Note:
  Resources allocated by the `HttpClient` may be reclaimed early by closing the client.
Implementation Note:

  The `HttpResponse.BodyHandlers` and `HttpResponse.BodySubscribers` classes provide some streaming or publishing `BodyHandler` and `BodySubscriber` implementations which allow to stream body data back to the caller. In order for the resources associated with these streams to be reclaimed, and for the HTTP request to be considered completed, a caller must eventually obtain the streaming response body and close, cancel, or read the returned streams to exhaustion. Likewise, a custom `HttpResponse.BodySubscriber` implementation should either request all data until `onComplete` or `onError` is signalled, or eventually cancel its subscription.

  The JDK built-in implementation of the `HttpClient` overrides `close()`, `shutdown()`, `shutdownNow()`, `awaitTermination(Duration)`, and `isTerminated()` to provide a best effort implementation. Failing to close, cancel, or read `streaming or publishing bodies` to exhaustion may stop delivery of data while leaving the request open, and stall an orderly shutdown. The `shutdownNow()` method, if called, will attempt to cancel any such non-completed requests, but may cause abrupt termination of any on going operation.

  If not explicitly closed, the JDK built-in implementation of the `HttpClient` releases its resources when an `HttpClient` instance is no longer strongly reachable, and all operations started on that instance have eventually completed. This relies both on the garbage collector to notice that the instance is no longer reachable, and on all requests started on the client to eventually complete. Failure to properly close streaming or publishing bodies may prevent the associated requests from running to completion, and prevent the resources allocated by the associated client from being reclaimed by the garbage collector.

  The default implementation of the `HttpClient` supports HTTP/1.1, HTTP/2, and HTTP/3. Which version of the protocol is actually used when sending a request can depend on multiple factors. In the case of HTTP/2, it may depend on an initial upgrade to succeed (when using a plain connection), or on HTTP/2 being successfully negotiated during the Transport Layer Security (TLS) handshake.

  If HTTP/2 is selected over a clear connection, and no HTTP/2 connection to the origin server already exists, the client will create a new connection and attempt an upgrade from HTTP/1.1 to HTTP/2. If the upgrade succeeds, then the response to this request will use HTTP/2. If the upgrade fails, then the response will be handled using HTTP/1.1.

  Other constraints may also affect the selection of protocol version. For example, if HTTP/2 is requested through a proxy, and if the implementation does not support this mode, then HTTP/1.1 may be used.

  The HTTP/3 protocol is not selected by default, but can be enabled by setting the HttpClient preferred version or the HttpRequest preferred version to HTTP/3. Like for HTTP/2, which protocol version is actually used when HTTP/3 is enabled may depend on several factors. Configuration hints can be provided to help the `HttpClient` implementation decide how to establish and carry out the HTTP exchange when the HTTP/3 protocol is enabled. If no configuration hints are provided, the `HttpClient` will select one as explained in the `H3_DISCOVERY` option API documentation.
  Note that a request whose URI scheme is not `"https"` will never be sent over HTTP/3. In this implementation, HTTP/3 is not used if a proxy is selected.

  If a concrete instance of `HttpClient` doesn't support sending a request through HTTP/3, an `UnsupportedProtocolVersionException` may be thrown, either when building the client with a preferred version set to HTTP/3, or when attempting to send a request with HTTP/3 enabled when `HTTP_3_URI_ONLY` was specified. This may typically happen if the `SSLContext` or `SSLParameters` configured on the client instance cannot be used with HTTP/3.

Since:
  11
See Also:
  - `UnsupportedProtocolVersionException`
  - `HttpClient.Builder.version(Version)`
  - `HttpRequest.Builder.version(Version)`
  - `HttpRequest.Builder.setOption(HttpOption, Object)`
  - `HttpOption.H3_DISCOVERY`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `HttpClient.Builder`
  A builder of HTTP Clients.
  `static enum`
  `HttpClient.Redirect`
  Defines the automatic redirection policy.
  `static enum`
  `HttpClient.Version`
  The HTTP protocol version.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `HttpClient()`
  Creates an HttpClient.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract Optional<Authenticator>`
  `authenticator()`
  Returns an `Optional` containing the `Authenticator` set on this client.
  `boolean`
  `awaitTermination(Duration duration)`
  Blocks until all operations have completed execution after a shutdown request, or the `duration` elapses, or the current thread is interrupted, whichever happens first.
  `void`
  `close()`
  Initiates an orderly shutdown in which requests previously submitted to `send` or `sendAsync` are run to completion, but no new request will be accepted.
  `abstract Optional<Duration>`
  `connectTimeout()`
  Returns an `Optional` containing the connect timeout duration for this client.
  `abstract Optional<CookieHandler>`
  `cookieHandler()`
  Returns an `Optional` containing this client's `CookieHandler`.
  `abstract Optional<Executor>`
  `executor()`
  Returns an `Optional` containing this client's `Executor`.
  `abstract HttpClient.Redirect`
  `followRedirects()`
  Returns the follow redirects policy for this client.
  `boolean`
  `isTerminated()`
  Returns `true` if all operations have completed following a shutdown.
  `static HttpClient.Builder`
  `newBuilder()`
  Creates a new `HttpClient` builder.
  `static HttpClient`
  `newHttpClient()`
  Returns a new `HttpClient` with default settings.
  `WebSocket.Builder`
  `newWebSocketBuilder()`
  Creates a new `WebSocket` builder (optional operation).
  `abstract Optional<ProxySelector>`
  `proxy()`
  Returns an `Optional` containing the `ProxySelector` supplied to this client.
  `abstract <T> HttpResponse<T>`
  `send(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler)`
  Sends the given request using this client, blocking if necessary to get the response.
  `abstract <T> CompletableFuture<HttpResponse<T>>`
  `sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler)`
  Sends the given request asynchronously using this client with the given response body handler.
  `abstract <T> CompletableFuture<HttpResponse<T>>`
  `sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler, HttpResponse.PushPromiseHandler<T> pushPromiseHandler)`
  Sends the given request asynchronously using this client with the given response body handler and push promise handler.
  `void`
  `shutdown()`
  Initiates an orderly shutdown in which requests previously submitted with `send` or `sendAsync` are run to completion, but no new request will be accepted.
  `void`
  `shutdownNow()`
  This method attempts to initiate an immediate shutdown.
  `abstract SSLContext`
  `sslContext()`
  Returns this client's `SSLContext`.
  `abstract SSLParameters`
  `sslParameters()`
  Returns a copy of this client's `SSLParameters`.
  `abstract HttpClient.Version`
  `version()`
  Returns the preferred HTTP protocol version for this client.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### HttpClient

    protected HttpClient()
    Creates an HttpClient.

- ## Method Details

  - ### newHttpClient

    public static HttpClient newHttpClient()
    Returns a new `HttpClient` with default settings.

    Equivalent to `newBuilder().build()`.

    The default settings include: the "GET" request method, a preference of HTTP/2, a redirection policy of NEVER, the default proxy selector, and the default SSL context.

    Implementation Note:
      The system-wide default values are retrieved at the time the `HttpClient` instance is constructed. Changing the system-wide values after an `HttpClient` instance has been built, for instance, by calling `ProxySelector.setDefault(ProxySelector)` or `SSLContext.setDefault(SSLContext)`, has no effect on already built instances.
    Returns:
      a new HttpClient
    Throws:
      `UncheckedIOException` - if necessary underlying IO resources required to build a new HttpClient cannot be allocated.

  - ### newBuilder

    public static HttpClient.Builder newBuilder()
    Creates a new `HttpClient` builder.

    Builders returned by this method create instances of the default `HttpClient` implementation.

    Returns:
      an `HttpClient.Builder`

  - ### cookieHandler

    public abstract Optional<CookieHandler> cookieHandler()
    Returns an `Optional` containing this client's `CookieHandler`. If no `CookieHandler` was set in this client's builder, then the `Optional` is empty.
    Returns:
      an `Optional` containing this client's `CookieHandler`

  - ### connectTimeout

    public abstract Optional<Duration> connectTimeout()
    Returns an `Optional` containing the connect timeout duration for this client. If the connect timeout duration was not set in the client's builder, then the `Optional` is empty.
    Returns:
      an `Optional` containing this client's connect timeout duration

  - ### followRedirects

    public abstract HttpClient.Redirect followRedirects()
    Returns the follow redirects policy for this client. The default value for client's built by builders that do not specify a redirect policy is `NEVER`.
    Returns:
      this client's follow redirects setting

  - ### proxy

    public abstract Optional<ProxySelector> proxy()
    Returns an `Optional` containing the `ProxySelector` supplied to this client. If no proxy selector was set in this client's builder, then the `Optional` is empty.

    Even though this method may return an empty optional, the `HttpClient` may still have a non-exposed default proxy selector that is used for sending HTTP requests.

    Returns:
      an `Optional` containing the proxy selector supplied to this client.

  - ### sslContext

    public abstract SSLContext sslContext()
    Returns this client's `SSLContext`.

    If no `SSLContext` was set in this client's builder, then the default context is returned.

    Returns:
      this client's SSLContext

  - ### sslParameters

    public abstract SSLParameters sslParameters()
    Returns a copy of this client's `SSLParameters`.

    If no `SSLParameters` were set in the client's builder, then an implementation specific default set of parameters, that the client will use, is returned.

    Returns:
      this client's `SSLParameters`

  - ### authenticator

    public abstract Optional<Authenticator> authenticator()
    Returns an `Optional` containing the `Authenticator` set on this client. If no `Authenticator` was set in the client's builder, then the `Optional` is empty.
    Returns:
      an `Optional` containing this client's `Authenticator`

  - ### version

    public abstract HttpClient.Version version()
    Returns the preferred HTTP protocol version for this client. The default value is `HttpClient.Version.HTTP_2`
    Implementation Note:
      The protocol version that the `HttpClient` eventually decides to use for a request is affected by various factors noted in protocol version selection section.
    Returns:
      the HTTP protocol version requested

  - ### executor

    public abstract Optional<Executor> executor()
    Returns an `Optional` containing this client's `Executor`. If no `Executor` was set in the client's builder, then the `Optional` is empty.

    Even though this method may return an empty optional, the `HttpClient` may still have an non-exposed default executor that is used for executing asynchronous and dependent tasks.

    Returns:
      an `Optional` containing this client's `Executor`

  - ### send

    public abstract <T> HttpResponse<T> send(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler) throws IOException, InterruptedException
    Sends the given request using this client, blocking if necessary to get the response. The returned `HttpResponse``<T>` contains the response status, headers, and body ( as handled by given response body handler ).

    If the operation is interrupted, the default `HttpClient` implementation attempts to cancel the HTTP exchange and `InterruptedException` is thrown. No guarantee is made as to exactly when the cancellation request may be taken into account. In particular, the request might still get sent to the server, as its processing might already have started asynchronously in another thread, and the underlying resources may only be released asynchronously.

    - With HTTP/1.1, an attempt to cancel may cause the underlying connection to be closed abruptly.
    - With HTTP/2, an attempt to cancel may cause the stream to be reset, or in certain circumstances, may also cause the connection to be closed abruptly, if, for instance, the thread is currently trying to write to the underlying socket.
    Type Parameters:
      `T` - the response body type
    Parameters:
      `request` - the request
      `responseBodyHandler` - the response body handler
    Returns:
      the response
    Throws:
      `IOException` - if an I/O error occurs when sending or receiving, or the client has shut down
      `InterruptedException` - if the operation is interrupted
      `IllegalArgumentException` - if the `request` argument is not a request that could have been validly built as specified by `HttpRequest.Builder`.

  - ### sendAsync

    public abstract <T> CompletableFuture<HttpResponse<T>> sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler)
    Sends the given request asynchronously using this client with the given response body handler.

    Equivalent to: `sendAsync(request, responseBodyHandler, null)`.

    Type Parameters:
      `T` - the response body type
    Parameters:
      `request` - the request
      `responseBodyHandler` - the response body handler
    Returns:
      a `CompletableFuture<HttpResponse<T>>`
    Throws:
      `IllegalArgumentException` - if the `request` argument is not a request that could have been validly built as specified by `HttpRequest.Builder`.

  - ### sendAsync

    public abstract <T> CompletableFuture<HttpResponse<T>> sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler, HttpResponse.PushPromiseHandler<T> pushPromiseHandler)
    Sends the given request asynchronously using this client with the given response body handler and push promise handler.

    The returned completable future, if completed successfully, completes with an `HttpResponse``<T>` that contains the response status, headers, and body ( as handled by given response body handler ).

    Push promises received, if any, are handled by the given `pushPromiseHandler`. A `null` valued `pushPromiseHandler` rejects any push promises.

    The returned completable future completes exceptionally with:

    - `IOException` - if an I/O error occurs when sending or receiving, or the client has shut down.

    The default `HttpClient` implementation returns `CompletableFuture` objects that are cancelable. `CompletableFuture` objects derived from cancelable futures are themselves cancelable. Invoking cancel(true) on a cancelable future that is not completed, attempts to cancel the HTTP exchange in an effort to release underlying resources as soon as possible. No guarantee is made as to exactly when the cancellation request may be taken into account. In particular, the request might still get sent to the server, as its processing might already have started asynchronously in another thread, and the underlying resources may only be released asynchronously.

    - With HTTP/1.1, an attempt to cancel may cause the underlying connection to be closed abruptly.
    - With HTTP/2, an attempt to cancel may cause the stream to be reset.
    Type Parameters:
      `T` - the response body type
    Parameters:
      `request` - the request
      `responseBodyHandler` - the response body handler
      `pushPromiseHandler` - push promise handler, may be null
    Returns:
      a `CompletableFuture<HttpResponse<T>>`
    Throws:
      `IllegalArgumentException` - if the `request` argument is not a request that could have been validly built as specified by `HttpRequest.Builder`.

  - ### newWebSocketBuilder

    public WebSocket.Builder newWebSocketBuilder()
    Creates a new `WebSocket` builder (optional operation).

    Example

        HttpClient client = HttpClient.newHttpClient();
        CompletableFuture<WebSocket> ws = client.newWebSocketBuilder()
           .buildAsync(URI.create("ws://websocket.example.com"), listener);

    Finer control over the WebSocket Opening Handshake can be achieved by using a custom `HttpClient`.

    Example

        InetSocketAddress addr = new InetSocketAddress("proxy.example.com", 80);
        HttpClient client = HttpClient.newBuilder()
                .proxy(ProxySelector.of(addr))
                .build();

        CompletableFuture<WebSocket> ws = client.newWebSocketBuilder()
                .buildAsync(URI.create("ws://websocket.example.com"), listener);

    Implementation Requirements:
      The default implementation of this method throws `UnsupportedOperationException`. Clients obtained through `newHttpClient()` or `newBuilder()` return a `WebSocket` builder.
    Implementation Note:
      Both builder and `WebSocket`s created with it operate in a non-blocking fashion. That is, their methods do not block before returning a `CompletableFuture`. Asynchronous tasks are executed in this `HttpClient`'s executor.

      When a `CompletionStage` returned from `Listener.onClose` completes, the `WebSocket` will send a Close message that has the same code the received message has and an empty reason.

    Returns:
      a `WebSocket.Builder`
    Throws:
      `UnsupportedOperationException` - if this `HttpClient` does not provide WebSocket support

  - ### shutdown

    public void shutdown()
    Initiates an orderly shutdown in which requests previously submitted with `send` or `sendAsync` are run to completion, but no new request will be accepted. Running a request to completion may involve running several operations in the background, including waiting for responses to be delivered, which will all have to run to completion until the request is considered completed. Invocation has no additional effect if already shut down.

    This method does not wait for previously submitted request to complete execution. Use `awaitTermination` or `close` to do that.

    Implementation Requirements:
      The default implementation of this method does nothing. Subclasses should override this method to implement the appropriate behavior.
    Since:
      21
    See Also:
      - Implementation Note on closing the HttpClient

  - ### awaitTermination

    public boolean awaitTermination(Duration duration) throws InterruptedException
    Blocks until all operations have completed execution after a shutdown request, or the `duration` elapses, or the current thread is interrupted, whichever happens first. Operations are any tasks required to run a request previously submitted with `send` or `sendAsync` to completion.

    This method does not wait if the duration to wait is less than or equal to zero. In this case, the method just tests if the thread has terminated.

    Implementation Requirements:
      The default implementation of this method checks for null arguments, but otherwise does nothing and returns true. Subclasses should override this method to implement the proper behavior.
    Parameters:
      `duration` - the maximum time to wait
    Returns:
      `true` if this client terminated and `false` if the timeout elapsed before termination
    Throws:
      `InterruptedException` - if interrupted while waiting
    Since:
      21
    See Also:
      - Implementation Note on closing the HttpClient

  - ### isTerminated

    public boolean isTerminated()
    Returns `true` if all operations have completed following a shutdown. Operations are any tasks required to run a request previously submitted with `send` or `sendAsync` to completion.

    Note that `isTerminated` is never `true` unless either `shutdown` or `shutdownNow` was called first.

    Implementation Requirements:
      The default implementation of this method does nothing and returns false. Subclasses should override this method to implement the proper behavior.
    Returns:
      `true` if all tasks have completed following a shutdown
    Since:
      21
    See Also:
      - Implementation Note on closing the HttpClient

  - ### shutdownNow

    public void shutdownNow()
    This method attempts to initiate an immediate shutdown. An implementation of this method may attempt to interrupt operations that are actively running. Operations are any tasks required to run a request previously submitted with `send` or `sendAsync` to completion. The behavior of actively running operations when interrupted is undefined. In particular, there is no guarantee that interrupted operations will terminate, or that code waiting on these operations will ever be notified.
    Implementation Requirements:
      The default implementation of this method simply calls `shutdown()`. Subclasses should override this method to implement the appropriate behavior.
    Since:
      21
    See Also:
      - Implementation Note on closing the HttpClient

  - ### close

    public void close()
    Initiates an orderly shutdown in which requests previously submitted to `send` or `sendAsync` are run to completion, but no new request will be accepted. Running a request to completion may involve running several operations in the background, including waiting for responses to be delivered. This method waits until all operations have completed execution and the client has terminated.

    If interrupted while waiting, this method may attempt to stop all operations by calling `shutdownNow()`. It then continues to wait until all actively executing operations have completed. The interrupted status will be re-asserted before this method returns.

    If already terminated, invoking this method has no effect.

    Specified by:
      `close` in interface `AutoCloseable`
    Implementation Requirements:
      The default implementation invokes `shutdown()` and waits for tasks to complete execution with `awaitTermination`.
    Since:
      21
    See Also:
      - Implementation Note on closing the HttpClient