Module java.net.http
Package java.net.http

Class 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. 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();
   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

    • 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 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

      • 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'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:
        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's Executor

      • 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
        • SecurityException - If a security manager has been installed and it denies access 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 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 WebSockets 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