← 返回首页
HttpClient (Java SE 26 & JDK 26)
JavaScript is disabled on your browser.
  1. java.net.http
  2. java.net.http
  3. HttpClient
Contents  
  1. Description
  2. Nested Class Summary
  3. Constructor Summary
  4. Method Summary
  5. Constructor Details
    1. HttpClient()
  6. Method Details
    1. newHttpClient()
    2. newBuilder()
    3. cookieHandler()
    4. connectTimeout()
    5. followRedirects()
    6. proxy()
    7. sslContext()
    8. sslParameters()
    9. authenticator()
    10. version()
    11. executor()
    12. send(HttpRequest, HttpResponse.BodyHandler)
    13. sendAsync(HttpRequest, HttpResponse.BodyHandler)
    14. sendAsync(HttpRequest, HttpResponse.BodyHandler, HttpResponse.PushPromiseHandler)
    15. newWebSocketBuilder()
    16. shutdown()
    17. awaitTermination(Duration)
    18. isTerminated()
    19. shutdownNow()
    20. close()
Hide sidebar  Show sidebar

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

Copy 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

Copy 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:

Report a bug or suggest an enhancement
For further API reference and developer documentation see the Java SE Documentation, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples. Other versions.
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 1993, 2026, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
All rights reserved. Use is subject to license terms and the documentation redistribution policy.

Scripting on this page tracks web page traffic, but does not change the content in any way.