HttpClient.Builder (Java SE 26 & JDK 26)
Description: declaration: module: java.net.http, package: java.net.http, class: HttpClient, interface: Builder
Keywords: java.net.http.HttpClient.Builder interface

# Interface HttpClient.Builder

Enclosing class:
  `HttpClient`

public static interface HttpClient.Builder
A builder of HTTP Clients.

Builders are created by invoking `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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ProxySelector`
  `NO_PROXY`
  A proxy selector that always return `Proxy.NO_PROXY` implying a direct connection.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `HttpClient.Builder`
  `authenticator(Authenticator authenticator)`
  Sets an authenticator to use for HTTP authentication.
  `HttpClient`
  `build()`
  Returns a new `HttpClient` built from the current state of this builder.
  `HttpClient.Builder`
  `connectTimeout(Duration duration)`
  Sets the connect timeout duration for this client.
  `HttpClient.Builder`
  `cookieHandler(CookieHandler cookieHandler)`
  Sets a cookie handler.
  `HttpClient.Builder`
  `executor(Executor executor)`
  Sets the executor to be used for asynchronous and dependent tasks.
  `HttpClient.Builder`
  `followRedirects(HttpClient.Redirect policy)`
  Specifies whether requests will automatically follow redirects issued by the server.
  `default HttpClient.Builder`
  `localAddress(InetAddress localAddr)`
  Binds the socket to this local address when creating connections for sending requests.
  `HttpClient.Builder`
  `priority(int priority)`
  Sets the default priority for any HTTP/2 requests sent from this client.
  `HttpClient.Builder`
  `proxy(ProxySelector proxySelector)`
  Sets a `ProxySelector`.
  `HttpClient.Builder`
  `sslContext(SSLContext sslContext)`
  Sets an `SSLContext`.
  `HttpClient.Builder`
  `sslParameters(SSLParameters sslParameters)`
  Sets an `SSLParameters`.
  `HttpClient.Builder`
  `version(HttpClient.Version version)`
  Sets the default preferred HTTP protocol version for requests issued by this client.

- ## Field Details

  - ### NO_PROXY

    static final ProxySelector NO_PROXY
    A proxy selector that always return `Proxy.NO_PROXY` implying a direct connection.

    This is a convenience object that can be passed to `proxy(ProxySelector)` in order to build an instance of `HttpClient` that uses no proxy.

- ## Method Details

  - ### cookieHandler

    HttpClient.Builder cookieHandler(CookieHandler cookieHandler)
    Sets a cookie handler.
    Parameters:
      `cookieHandler` - the cookie handler
    Returns:
      this builder

  - ### connectTimeout

    HttpClient.Builder connectTimeout(Duration duration)
    Sets the connect timeout duration for this client.

    In the case where a new connection needs to be established, if the connection cannot be established within the given `duration`, then `HttpClient::send` throws an `HttpConnectTimeoutException`, or `HttpClient::sendAsync` completes exceptionally with an `HttpConnectTimeoutException`. If a new connection does not need to be established, for example if a connection can be reused from a previous request, then this timeout duration has no effect.

    Implementation Requirements:
      A connection timeout applies to the entire connection phase, from the moment a connection is requested until it is established. Implementations are recommended to ensure that the connection timeout covers any SSL/TLS handshakes.
    Implementation Note:
      The built-in JDK implementation of the connection timeout covers any SSL/TLS handshakes.
    Parameters:
      `duration` - the duration to allow the underlying connection to be established
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if the duration is non-positive
    See Also:
      - Configuring timeout for request execution

  - ### sslContext

    HttpClient.Builder sslContext(SSLContext sslContext)
    Sets an `SSLContext`.

    If this method is not invoked prior to building, then newly built clients will use the default context, which is normally adequate for client applications that do not need to specify protocols, or require client authentication.

    Parameters:
      `sslContext` - the SSLContext
    Returns:
      this builder

  - ### sslParameters

    HttpClient.Builder sslParameters(SSLParameters sslParameters)
    Sets an `SSLParameters`.

    If this method is not invoked prior to 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.

    Parameters:
      `sslParameters` - the SSLParameters
    Returns:
      this builder

  - ### executor

    HttpClient.Builder executor(Executor executor)
    Sets the executor to be used for asynchronous and dependent tasks.

    If this method is not invoked prior to building, a default executor is created for each newly built `HttpClient`.

    Implementation Note:
      The default executor uses a thread pool, with a custom thread factory.
    Parameters:
      `executor` - the Executor
    Returns:
      this builder

  - ### followRedirects

    HttpClient.Builder followRedirects(HttpClient.Redirect policy)
    Specifies whether requests will automatically follow redirects issued by the server.

    If this method is not invoked prior to building, then newly built clients will use a default redirection policy of `NEVER`.

    Parameters:
      `policy` - the redirection policy
    Returns:
      this builder

  - ### version

    HttpClient.Builder version(HttpClient.Version version)
    Sets the default preferred HTTP protocol version for requests issued by this client.

    If this method is not invoked prior to building, then newly built clients will prefer HTTP/2.

    If a request doesn't have a preferred version, then the effective preferred version for the request is the client's preferred version.

    Implementation Note:
      Some constraints may also affect the selection of the actual protocol version.
    Parameters:
      `version` - the requested HTTP protocol version
    Returns:
      this builder

  - ### priority

    HttpClient.Builder priority(int priority)
    Sets the default priority for any HTTP/2 requests sent from this client. The value provided must be between `1` and `256` (inclusive).
    Parameters:
      `priority` - the priority weighting
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if the given priority is out of range

  - ### proxy

    HttpClient.Builder proxy(ProxySelector proxySelector)
    Sets a `ProxySelector`.
    API Note:
      `ProxySelector::of` provides a `ProxySelector` which uses a single proxy for all requests. The system-wide proxy selector can be retrieved by `ProxySelector.getDefault()`.
    Implementation Note:
      If this method is not invoked prior to building, then newly built clients will use the 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 `NO_PROXY` or one returned by `ProxySelector::of`, before building.
    Parameters:
      `proxySelector` - the ProxySelector
    Returns:
      this builder

  - ### authenticator

    HttpClient.Builder authenticator(Authenticator authenticator)
    Sets an authenticator to use for HTTP authentication.
    Implementation Note:
      In the JDK built-in implementation of the `HttpClient`, if a `HttpRequest` has an `Authorization` or `Proxy-Authorization` header set then its value is used and the `Authenticator` is not invoked for the corresponding authentication. In this case, any authentication errors are returned to the user and requests are not automatically retried. Additionally, the JDK built-in implementation currently only supports HTTP `Basic` authentication.
    Parameters:
      `authenticator` - the Authenticator
    Returns:
      this builder

  - ### localAddress

    default HttpClient.Builder localAddress(InetAddress localAddr)
    Binds the socket to this local address when creating connections for sending requests.

    If no local address is set or `null` is passed to this method then sockets created by the HTTP client will be bound to an automatically assigned socket address.

    Common usages of the `HttpClient` do not require this method to be called. Setting a local address, through this method, is only for advanced usages where users of the `HttpClient` require specific control on which network interface gets used for the HTTP communication. Callers of this method are expected to be aware of the networking configurations of the system where the `HttpClient` will be used and care should be taken to ensure the correct `localAddr` is passed. Failure to do so can result in requests sent through the `HttpClient` to fail.

    Implementation Requirements:
      The default implementation of this method throws `UnsupportedOperationException`. `Builder`s obtained through `HttpClient.newBuilder()` provide an implementation of this method that allows setting the local address.
    Parameters:
      `localAddr` - The local address of the socket. Can be null.
    Returns:
      this builder
    Throws:
      `UnsupportedOperationException` - if this builder doesn't support configuring a local address or if the passed `localAddr` is not supported by this `HttpClient` implementation.
    Since:
      19

  - ### build

    HttpClient build()
    Returns a new `HttpClient` built from the current state of this builder.
    Returns:
      a new `HttpClient`
    Throws:
      `UncheckedIOException` - may be thrown if underlying IO resources required by the implementation cannot be allocated, or if the resulting configuration does not satisfy the implementation requirements. For instance, if the implementation requires a `Selector`, and opening one fails due to lack of necessary resources, or if the preferred protocol version is not supported by the implementation or cannot be used in this configuration.