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

## Class HttpClient

- java.lang.Object
- - jdk.incubator.http.HttpClient

-     public abstract class HttpClient
      extends Object

  A container for configuration information common to multiple `HttpRequest`s. All requests are sent through a `HttpClient`.
  Incubating Feature. Will be removed in a future release.

  `HttpClient`s 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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `HttpClient.Builder` | A builder of immutable `HttpClient`s.
    `static class` | `HttpClient.Redirect` | Defines automatic redirection policy.
    `static class` | `HttpClient.Version` | The HTTP protocol version.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `HttpClient​()` | Creates an HttpClient.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract Optional<Authenticator>` | `authenticator​()` | Returns an `Optional` containing the `Authenticator` set on this client.
    `abstract Optional<CookieManager>` | `cookieManager​()` | Returns an `Optional` which contains this client's `CookieManager`.
    `abstract Executor` | `executor​()` | Returns the `Executor` set on this client.
    `abstract HttpClient.Redirect` | `followRedirects​()` | Returns the follow-redirects setting for this client.
    `static HttpClient.Builder` | `newBuilder​()` | Creates a new `HttpClient` builder.
    `static HttpClient` | `newHttpClient​()` | Returns a new HttpClient with default settings.
    `WebSocket.Builder` | `newWebSocketBuilder​(URI uri, WebSocket.Listener listener)` | Creates a builder of `WebSocket` instances connected to the given URI and receiving events and messages with the given `Listener`.
    `abstract Optional<ProxySelector>` | `proxy​()` | Returns an `Optional` containing the `ProxySelector` for this client.
    `abstract <T> HttpResponse<T>` | `send​(HttpRequest req, 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 req, HttpResponse.BodyHandler<T> responseBodyHandler)` | Sends the given request asynchronously using this client and the given response handler.
    `abstract <U,T> CompletableFuture<U>` | `sendAsync​(HttpRequest req, HttpResponse.MultiProcessor<U,T> multiProcessor)` | Sends the given request asynchronously using this client and the given multi response handler.
    `abstract SSLContext` | `sslContext​()` | Returns the `SSLContext`, if one was set on this client.
    `abstract Optional<SSLParameters>` | `sslParameters​()` | Returns an `Optional` containing the `SSLParameters` set on this client.
    `abstract HttpClient.Version` | `version​()` | Returns the HTTP protocol version requested for this client.

    - ### Methods inherited from 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.
      Returns:
        a new HttpClient

    - #### newBuilder

          public static HttpClient.Builder newBuilder​()

      Creates a new `HttpClient` builder.
      Returns:
        a `HttpClient.Builder`

    - #### cookieManager

          public abstract Optional<CookieManager> cookieManager​()

      Returns an `Optional` which contains this client's `CookieManager`. If no `CookieManager` was set in this client's builder, then the `Optional` is empty.
      Returns:
        an `Optional` containing this client's `CookieManager`

    - #### followRedirects

          public abstract HttpClient.Redirect followRedirects​()

      Returns the follow-redirects setting for this client. The default value for this setting is `HttpClient.Redirect.NEVER`
      Returns:
        this client's follow redirects setting

    - #### proxy

          public abstract Optional<ProxySelector> proxy​()

      Returns an `Optional` containing the `ProxySelector` for this client. If no proxy is set then the `Optional` is empty.
      Returns:
        an `Optional` containing this client's proxy selector

    - #### sslContext

          public abstract SSLContext sslContext​()

      Returns the `SSLContext`, if one was set on this client. If a security manager is set, then the caller must have the `NetPermission`("getSSLContext") permission. If no `SSLContext` was set, then the default context is returned.
      Returns:
        this client's SSLContext
      Throws:
        `SecurityException` - if the caller does not have permission to get the SSLContext

    - #### sslParameters

          public abstract Optional<SSLParameters> sslParameters​()

      Returns an `Optional` containing the `SSLParameters` set on this client. If no `SSLParameters` were set in the client's builder, then the `Optional` is empty.
      Returns:
        an `Optional` containing 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 HTTP protocol version requested for this client. The default value is `HttpClient.Version.HTTP_2`
      Returns:
        the HTTP protocol version requested

    - #### executor

          public abstract Executor executor​()

      Returns the `Executor` set on this client. If an `Executor` was not set on the client's builder, then a default object is returned. The default `Executor` is created independently for each client.
      Returns:
        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

    - #### 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.
      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.MultiProcessor<U,T> multiProcessor)

      Sends the given request asynchronously using this client and the given multi response handler.
      Type Parameters:
        `U` - a type representing the aggregated results
        `T` - a type representing all of the response bodies
      Parameters:
        `req` - the request
        `multiProcessor` - the MultiProcessor for the request
      Returns:
        a `CompletableFuture<U>`

    - #### newWebSocketBuilder

          public WebSocket.Builder newWebSocketBuilder​(URI uri,
                                                       WebSocket.Listener listener)

      Creates a builder of `WebSocket` instances connected to the given URI and receiving events and messages with the given `Listener`.

      Example

               HttpClient client = HttpClient.newHttpClient();
               WebSocket.Builder builder = client.newWebSocketBuilder(
                       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();
               WebSocket.Builder builder = client.newWebSocketBuilder(
                       URI.create("ws://websocket.example.com"),
                       listener);

      Implementation Requirements:
        The default implementation of this method throws `UnsupportedOperationException`. However, clients obtained through `newHttpClient()` or `newBuilder()` provide WebSocket capability.
      Parameters:
        `uri` - the WebSocket URI
        `listener` - the listener
      Returns:
        a builder of `WebSocket` instances
      Throws:
        `UnsupportedOperationException` - if this `HttpClient` does not provide WebSocket support