An {@code HttpClient} can be used to send {@linkplain HttpRequest * requests} and retrieve their {@linkplain HttpResponse responses}. An {@code * HttpClient} is created through a {@link HttpClient#newBuilder() 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 {@code HttpClient} is immutable, * and can be used to send multiple requests. * *
An {@code HttpClient} provides configuration information, and resource * sharing, for all requests sent through it. * *
A {@link BodyHandler BodyHandler} must be supplied for each {@link * HttpRequest} sent. The {@code BodyHandler} determines how to handle the * response body, if any. Once an {@link 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, {@code T}, of * the response body. * *
Requests can be sent either synchronously or asynchronously: *
Synchronous Example *
{@code HttpClient client = HttpClient.newBuilder()
* .version(Version.HTTP_1_1)
* .followRedirects(Redirect.NORMAL)
* .proxy(ProxySelector.of(new InetSocketAddress("proxy.example.com", 80)))
* .authenticator(Authenticator.getDefault())
* .build();
* HttpResponse response = client.send(request, BodyHandlers.ofString());
* System.out.println(response.statusCode());
* System.out.println(response.body()); }
*
* Asynchronous Example *
{@code HttpRequest request = HttpRequest.newBuilder()
* .uri(URI.create("https://foo.com/"))
* .timeout(Duration.ofMinutes(1))
* .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); }
*
* If a security manager is present then security checks are performed by * the HTTP Client's sending methods. An appropriate {@link URLPermission} is * required to access the destination server, and proxy server if one has * been configured. The form of the {@code URLPermission} required to access a * proxy has a {@code method} parameter of {@code "CONNECT"} (for all kinds of * proxying) and a {@code URL} string of the form {@code "socket://host:port"} * where host and port specify the proxy's address. * * @implNote If an explicit {@linkplain HttpClient.Builder#executor(Executor) * executor} has not been set for an {@code 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 * {@linkplain HttpRequest.BodyPublisher request body publishers}, {@linkplain * HttpResponse.BodyHandler response body handlers}, {@linkplain * HttpResponse.BodySubscriber response body subscribers}, and {@linkplain * WebSocket.Listener WebSocket Listeners}, if executing operations that require * privileges, should do so within an appropriate {@linkplain * AccessController#doPrivileged(PrivilegedAction) privileged context}. * * @since 11 */ public abstract class HttpClient { /** * Creates an HttpClient. */ protected HttpClient() {} /** * Returns a new {@code HttpClient} with default settings. * *
Equivalent to {@code newBuilder().build()}. * *
The default settings include: the "GET" request method, a preference * of {@linkplain HttpClient.Version#HTTP_2 HTTP/2}, a redirection policy of * {@linkplain Redirect#NEVER NEVER}, the {@linkplain * ProxySelector#getDefault() default proxy selector}, and the {@linkplain * SSLContext#getDefault() default SSL context}. * * @implNote The system-wide default values are retrieved at the time the * {@code HttpClient} instance is constructed. Changing the system-wide * values after an {@code HttpClient} instance has been built, for * instance, by calling {@link ProxySelector#setDefault(ProxySelector)} * or {@link SSLContext#setDefault(SSLContext)}, has no effect on already * built instances. * * @return a new HttpClient */ public static HttpClient newHttpClient() { return newBuilder().build(); } /** * Creates a new {@code HttpClient} builder. * * @return an {@code HttpClient.Builder} */ public static Builder newBuilder() { return new HttpClientBuilderImpl(); } /** * A builder of {@linkplain HttpClient HTTP Clients}. * *
Builders are created by invoking {@link HttpClient#newBuilder() * newBuilder}. Each of the setter methods modifies the state of the builder * and returns the same instance. Builders are not thread-safe and should not be * used concurrently from multiple threads without external synchronization. * * @since 11 */ public interface Builder { /** * A proxy selector that always return {@link Proxy#NO_PROXY} implying * a direct connection. * *
This is a convenience object that can be passed to * {@link #proxy(ProxySelector)} in order to build an instance of * {@link HttpClient} that uses no proxy. */ public static final ProxySelector NO_PROXY = ProxySelector.of(null); /** * Sets a cookie handler. * * @param cookieHandler the cookie handler * @return this builder */ public Builder cookieHandler(CookieHandler cookieHandler); /** * Sets an {@code SSLContext}. * *
If this method is not invoked prior to {@linkplain #build() * building}, then newly built clients will use the {@linkplain * SSLContext#getDefault() default context}, which is normally adequate * for client applications that do not need to specify protocols, or * require client authentication. * * @param sslContext the SSLContext * @return this builder */ public Builder sslContext(SSLContext sslContext); /** * Sets an {@code SSLParameters}. * *
If this method is not invoked prior to {@linkplain #build() * building}, then newly built clients will use a default, * implementation specific, set of parameters. * *
Some parameters which are used internally by the HTTP Client * implementation (such as the application protocol list) should not be * set by callers, as they may be ignored. The contents of the given * object are copied. * * @param sslParameters the SSLParameters * @return this builder */ public Builder sslParameters(SSLParameters sslParameters); /** * Sets the executor to be used for asynchronous and dependent tasks. * *
If this method is not invoked prior to {@linkplain #build() * building}, a default executor is created for each newly built {@code * HttpClient}. * * @implNote The default executor uses a thread pool, with a custom * thread factory. If a security manager has been installed, the thread * factory creates threads that run with an access control context that * has no permissions. * * @param executor the Executor * @return this builder */ public Builder executor(Executor executor); /** * Specifies whether requests will automatically follow redirects issued * by the server. * *
If this method is not invoked prior to {@linkplain #build() * building}, then newly built clients will use a default redirection * policy of {@link Redirect#NEVER NEVER}. * * @param policy the redirection policy * @return this builder */ public Builder followRedirects(Redirect policy); /** * Requests a specific HTTP protocol version where possible. * *
If this method is not invoked prior to {@linkplain #build() * building}, then newly built clients will prefer {@linkplain * Version#HTTP_2 HTTP/2}. * *
If set to {@linkplain Version#HTTP_2 HTTP/2}, then each request
* will attempt to upgrade to HTTP/2. If the upgrade succeeds, then the
* response to this request will use HTTP/2 and all subsequent requests
* and responses to the same
* origin server
* will use HTTP/2. If the upgrade fails, then the response will be
* handled using HTTP/1.1
*
* @implNote 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
*
* @param version the requested HTTP protocol version
* @return this builder
*/
public Builder version(HttpClient.Version version);
/**
* Sets the default priority for any HTTP/2 requests sent from this
* client. The value provided must be between {@code 1} and {@code 256}
* (inclusive).
*
* @param priority the priority weighting
* @return this builder
* @throws IllegalArgumentException if the given priority is out of range
*/
public Builder priority(int priority);
/**
* Sets a {@link java.net.ProxySelector}.
*
* @apiNote {@link ProxySelector#of(InetSocketAddress) ProxySelector::of}
* provides a {@code ProxySelector} which uses a single proxy for all
* requests. The system-wide proxy selector can be retrieved by
* {@link ProxySelector#getDefault()}.
*
* @implNote
* If this method is not invoked prior to {@linkplain #build() building},
* then newly built clients will use the {@linkplain
* ProxySelector#getDefault() default proxy selector}, which is usually
* adequate for client applications. The default proxy selector supports
* a set of system properties related to
*
* proxy settings. This default behavior can be disabled by
* supplying an explicit proxy selector, such as {@link #NO_PROXY} or
* one returned by {@link ProxySelector#of(InetSocketAddress)
* ProxySelector::of}, before {@linkplain #build() building}.
*
* @param proxySelector the ProxySelector
* @return this builder
*/
public Builder proxy(ProxySelector proxySelector);
/**
* Sets an authenticator to use for HTTP authentication.
*
* @param authenticator the Authenticator
* @return this builder
*/
public Builder authenticator(Authenticator authenticator);
/**
* Returns a new {@link HttpClient} built from the current state of this
* builder.
*
* @return a new {@code HttpClient}
*/
public HttpClient build();
}
/**
* Returns an {@code Optional} containing this client's {@link
* CookieHandler}. If no {@code CookieHandler} was set in this client's
* builder, then the {@code Optional} is empty.
*
* @return an {@code Optional} containing this client's {@code CookieHandler}
*/
public abstract Optional Even though this method may return an empty optional, the {@code
* HttpClient} may still have a non-exposed {@linkplain
* Builder#proxy(ProxySelector) default proxy selector} that is
* used for sending HTTP requests.
*
* @return an {@code Optional} containing the proxy selector supplied
* to this client.
*/
public abstract Optional If no {@code SSLContext} was set in this client's builder, then the
* {@linkplain SSLContext#getDefault() default context} is returned.
*
* @return this client's SSLContext
*/
public abstract SSLContext sslContext();
/**
* Returns a copy of this client's {@link SSLParameters}.
*
* If no {@code SSLParameters} were set in the client's builder, then an
* implementation specific default set of parameters, that the client will
* use, is returned.
*
* @return this client's {@code SSLParameters}
*/
public abstract SSLParameters sslParameters();
/**
* Returns an {@code Optional} containing the {@link Authenticator} set on
* this client. If no {@code Authenticator} was set in the client's builder,
* then the {@code Optional} is empty.
*
* @return an {@code Optional} containing this client's {@code Authenticator}
*/
public abstract Optional Even though this method may return an empty optional, the {@code
* HttpClient} may still have an non-exposed {@linkplain
* HttpClient.Builder#executor(Executor) default executor} that is used for
* executing asynchronous and dependent tasks.
*
* @return an {@code Optional} containing this client's {@code Executor}
*/
public abstract Optional The automatic redirection policy is checked whenever a {@code 3XX}
* response code is received. If redirection does not happen automatically,
* then the response, containing the {@code 3XX} response code, is returned,
* where it can be handled manually.
*
* {@code Redirect} policy is set through the {@linkplain
* HttpClient.Builder#followRedirects(Redirect) Builder.followRedirects}
* method.
*
* @implNote When automatic redirection occurs, the request method of the
* redirected request may be modified depending on the specific {@code 30X}
* status code, as specified in
* RFC 7231. In addition, the {@code 301} and {@code 302} status codes
* cause a {@code POST} request to be converted to a {@code GET} in the
* redirected request.
*
* @since 11
*/
public enum Redirect {
/**
* Never redirect.
*/
NEVER,
/**
* Always redirect.
*/
ALWAYS,
/**
* Always redirect, except from HTTPS URLs to HTTP URLs.
*/
NORMAL
}
/**
* Sends the given request using this client, blocking if necessary to get
* the response. The returned {@link HttpResponse}{@code Equivalent to: {@code sendAsync(request, responseBodyHandler, null)}.
*
* @param The returned completable future, if completed successfully, completes
* with an {@link HttpResponse}{@code {@linkplain PushPromiseHandler Push promises} received, if any, are
* handled by the given {@code pushPromiseHandler}. A {@code null} valued
* {@code pushPromiseHandler} rejects any push promises.
*
* The returned completable future completes exceptionally with:
* Example
* Finer control over the WebSocket Opening Handshake can be achieved
* by using a custom {@code HttpClient}.
*
* Example
* When a {@code CompletionStage} returned from
* {@link WebSocket.Listener#onClose Listener.onClose} completes,
* the {@code WebSocket} will send a Close message that has the same code
* the received message has and an empty reason.
*
* @return a {@code WebSocket.Builder}
* @throws UnsupportedOperationException
* if this {@code HttpClient} does not provide WebSocket support
*/
public WebSocket.Builder newWebSocketBuilder() {
throw new UnsupportedOperationException();
}
}
*
*
* @param {@code HttpClient client = HttpClient.newHttpClient();
* CompletableFuture
*
* {@code InetSocketAddress addr = new InetSocketAddress("proxy.example.com", 80);
* HttpClient client = HttpClient.newBuilder()
* .proxy(ProxySelector.of(addr))
* .build();
* CompletableFuture
*
* @implSpec The default implementation of this method throws
* {@code UnsupportedOperationException}. Clients obtained through
* {@link HttpClient#newHttpClient()} or {@link HttpClient#newBuilder()}
* return a {@code WebSocket} builder.
*
* @implNote Both builder and {@code WebSocket}s created with it operate in
* a non-blocking fashion. That is, their methods do not block before
* returning a {@code CompletableFuture}. Asynchronous tasks are executed in
* this {@code HttpClient}'s executor.
*
*