Module jdk.incubator.httpclient
Package jdk.incubator.http

Class HttpClient

  • public abstract class HttpClient
extends Object
    A container for configuration information common to multiple HttpRequests. All requests are sent through a HttpClient.
    Incubating Feature. Will be removed in a future release.

    HttpClients are immutable and created from a builder returned from newBuilder(). Request builders are created by calling HttpRequest.newBuilder().

    See HttpRequest for examples of usage of this API.

    Since:
    9

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

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

      • 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 req,
                                         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:
        req - the request
        responseBodyHandler - the response body handler
        Returns:
        the response body
        Throws:
        IOException - if an I/O error occurs when sending or receiving
        InterruptedException - if the operation is interrupted
        IllegalArgumentException - if the request method is not supported
        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 HttpRequest for further information about security checks.

      • sendAsync

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

        The returned completable future completes exceptionally with:

        Type Parameters:
        T - the response body type
        Parameters:
        req - the request
        responseBodyHandler - the response body handler
        Returns:
        a CompletableFuture<HttpResponse<T>>

      • sendAsync

        public abstract <U,T> CompletableFuture<U> sendAsync​(HttpRequest req,
                                                     HttpResponse.MultiSubscriber<U,T> multiSubscriber)
        Sends the given request asynchronously using this client and the given multi response handler.

        The returned completable future completes exceptionally with:

        Type Parameters:
        U - a type representing the aggregated results
        T - a type representing all of the response bodies
        Parameters:
        req - the request
        multiSubscriber - the multiSubscriber for the request
        Returns:
        a CompletableFuture<U>

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

        A WebSocket.Builder returned from this method is not safe for use by multiple threads without external synchronization.

        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