Class HttpClient
- java.lang.Object
-
- java.net.http.HttpClient
public abstract class HttpClient extends Object
An HTTP Client.
An HttpClient
can be used to send requests and retrieve their responses. An
HttpClient
is created through a builder
. The builder can be used to configure per-client state, like: the preferred protocol version ( HTTP/1.1 or HTTP/2 ), 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.
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. ThesendAsync
method returns immediately with aCompletableFuture
<HttpResponse
>. TheCompletableFuture
completes when the response becomes available. The returnedCompletableFuture
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(); 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);
Security checks
If a security manager is present then security checks are performed by the HTTP Client's sending methods. An appropriate URLPermission
is required to access the destination server, and proxy server if one has been configured. The form of the URLPermission
required to access a proxy has a method
parameter of "CONNECT"
(for all kinds of proxying) and a URL
string of the form "socket://host:port"
where host and port specify the proxy's address.
- Implementation Note:
- If an explicit executor has not been set for an
HttpClient
, and a security manager has been installed, then the default executor will execute asynchronous and dependent tasks in a context that is granted no permissions. Custom request body publishers, response body handlers, response body subscribers, and WebSocket Listeners, if executing operations that require privileges, should do so within an appropriate privileged context. - Since:
- 11
Nested Class Summary
Modifier and Type | Class | Description |
---|---|---|
static interface | HttpClient.Builder | A builder of HTTP Clients. |
static class | HttpClient.Redirect | Defines the automatic redirection policy. |
static class | HttpClient.Version | The HTTP protocol version. |
Constructor Summary
Modifier | Constructor | Description |
---|---|---|
protected | HttpClient() | Creates an HttpClient. |
Method Summary
Modifier and Type | Method | Description |
---|---|---|
abstract Optional<Authenticator> | authenticator() | Returns an |
abstract Optional<Duration> | connectTimeout() | Returns an |
abstract Optional<CookieHandler> | cookieHandler() | Returns an |
abstract Optional<Executor> | executor() | Returns an |
abstract HttpClient.Redirect | followRedirects() | Returns the follow redirects policy for this client. |
static HttpClient.Builder | newBuilder() | Creates a new |
static HttpClient | newHttpClient() | Returns a new |
WebSocket.Builder | newWebSocketBuilder() | Creates a new |
abstract Optional<ProxySelector> | proxy() | Returns an |
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. |
abstract SSLContext | sslContext() | Returns this client's |
abstract SSLParameters | sslParameters() | Returns a copy of this client's |
abstract HttpClient.Version | version() | Returns the preferred HTTP protocol version for this client. |
Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Constructor Detail
HttpClient
protected HttpClient()
Creates an HttpClient.
Method Detail
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 anHttpClient
instance has been built, for instance, by callingProxySelector.setDefault(ProxySelector)
orSSLContext.setDefault(SSLContext)
, has no effect on already built instances. - Returns:
- a new HttpClient
newBuilder
public static HttpClient.Builder newBuilder()
Creates a new HttpClient
builder.
- 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'sCookieHandler
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'sAuthenticator
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:
- 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
- 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'sExecutor
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 ).
- 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 -
InterruptedException
- if the operation is interrupted -
IllegalArgumentException
- if therequest
argument is not a request that could have been validly built as specified byHttpRequest.Builder
. -
SecurityException
- If a security manager has been installed and it deniesaccess
to the URL in the given request, or proxy if one is configured. See security checks for further information.
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 therequest
argument is not a request that could have been validly built as specified byHttpRequest.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 -
SecurityException
- If a security manager has been installed and it deniesaccess
to the URL in the given request, or proxy if one is configured. See security checks for further information.
- 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 therequest
argument is not a request that could have been validly built as specified byHttpRequest.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 throughnewHttpClient()
ornewBuilder()
return aWebSocket
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 aCompletableFuture
. Asynchronous tasks are executed in thisHttpClient
's executor.When a
CompletionStage
returned fromListener.onClose
completes, theWebSocket
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 thisHttpClient
does not provide WebSocket support