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

Interface HttpClient.Builder

封装类:
HttpClient
public static interface HttpClient.Builder
HTTP客户端的构建器。

通过调用newBuilder来创建构建器。每个setter方法修改构建器的状态并返回相同的实例。构建器不是线程安全的，不应在多个线程中并发使用，除非进行外部同步。

自 JDK 版本:
11

  • Field Details

  • Method Details

    • cookieHandler

      HttpClient.Builder cookieHandler(CookieHandler cookieHandler)
      设置一个cookie处理程序。
      参数:
      cookieHandler - cookie处理程序
      返回:
      此构建器

    • connectTimeout

      HttpClient.Builder connectTimeout(Duration duration)
      设置此客户端的连接超时持续时间。

      在需要建立新连接的情况下，如果连接无法在给定的持续时间内建立，则HttpClient::send会抛出一个HttpConnectTimeoutException，或者HttpClient::sendAsync会异常完成，带有一个HttpConnectTimeoutException。如果不需要建立新连接，例如如果可以重用来自先前请求的连接，则此超时持续时间不起作用。

      参数:
      duration - 允许建立底层连接的持续时间
      返回:
      此构建器
      抛出:
      IllegalArgumentException - 如果持续时间为非正数

    • sslContext

      HttpClient.Builder sslContext(SSLContext sslContext)
      设置一个SSLContext。

      如果在构建之前未调用此方法，则新构建的客户端将使用默认上下文，通常适用于不需要指定协议或需要客户端身份验证的客户端应用程序。

      参数:
      sslContext - SSL上下文
      返回:
      此构建器

    • sslParameters

      HttpClient.Builder sslParameters(SSLParameters sslParameters)
      设置一个SSLParameters。

      如果在构建之前未调用此方法，则新构建的客户端将使用默认的、特定于实现的一组参数。

      一些由HTTP客户端实现内部使用的参数（例如应用程序协议列表）不应该由调用者设置，因为它们可能会被忽略。给定对象的内容将被复制。

      参数:
      sslParameters - SSL参数
      返回:
      此构建器

    • executor

      HttpClient.Builder executor(Executor executor)
      设置用于异步和依赖任务的执行程序。

      如果在构建之前未调用此方法，则为每个新构建的HttpClient创建一个默认执行程序。

      实现说明:
      默认执行程序使用线程池，带有自定义线程工厂。如果已安装安全管理器，则线程工厂创建的线程将以没有权限的访问控制上下文运行。
      参数:
      executor - 执行程序
      返回:
      此构建器

    • followRedirects

      HttpClient.Builder followRedirects(HttpClient.Redirect policy)
      指定请求是否会自动遵循服务器发出的重定向。

      如果在构建之前未调用此方法，则新构建的客户端将使用默认的重定向策略NEVER。

      参数:
      policy - 重定向策略
      返回:
      此构建器

    • version

      HttpClient.Builder version(HttpClient.Version version)
      在可能的情况下请求特定的HTTP协议版本。

      如果在构建之前未调用此方法，则新构建的客户端将优先选择HTTP/2。

      如果设置为HTTP/2，则每个请求将尝试升级到HTTP/2。如果升级成功，则对此请求的响应将使用HTTP/2，并且所有后续请求和响应到相同的源服务器将使用HTTP/2。如果升级失败，则响应将使用HTTP/1.1处理。

      实现说明:
      约束也可能影响协议版本的选择。例如，如果通过代理请求HTTP/2，并且实现不支持此模式，则可能会使用HTTP/1.1
      参数:
      version - 请求的HTTP协议版本
      返回:
      此构建器

    • priority

      HttpClient.Builder priority(int priority)
      设置从此客户端发送的任何HTTP/2请求的默认优先级。提供的值必须在1和256之间（包括边界值）。
      参数:
      priority - 优先级权重
      返回:
      此构建器
      抛出:
      IllegalArgumentException - 如果给定的优先级超出范围

    • proxy

      HttpClient.Builder proxy(ProxySelector proxySelector)
      设置一个ProxySelector。
      API说明:
      ProxySelector::of提供一个为所有请求使用单个代理的ProxySelector。可以通过ProxySelector.getDefault()检索系统范围的代理选择器。
      实现说明:
      如果在构建之前未调用此方法，则新构建的客户端将使用默认代理选择器，通常适用于客户端应用程序。默认代理选择器支持与代理设置相关的一组系统属性。可以通过在构建之前提供显式代理选择器（例如NO_PROXY或由ProxySelector::of返回的代理选择器）来禁用此默认行为。
      参数:
      proxySelector - 代理选择器
      返回:
      此构建器

    • authenticator

      HttpClient.Builder authenticator(Authenticator authenticator)
      设置用于HTTP身份验证的认证器。
      参数:
      authenticator - 认证器
      返回:
      此构建器

    • localAddress

      default HttpClient.Builder localAddress(InetAddress localAddr)
      在发送请求时，为创建连接将套接字绑定到此本地地址。

      如果未设置本地地址或将null传递给此方法，则HTTP客户端创建的套接字将绑定到自动分配的套接字地址。

      通常使用HttpClient不需要调用此方法。通过此方法设置本地地址仅适用于高级用法，其中HttpClient的用户需要对用于HTTP通信的网络接口进行特定控制。调用此方法的调用方应该了解将使用HttpClient的系统的网络配置，并应注意确保传递正确的localAddr。否则可能导致通过HttpClient发送的请求失败。

      实现要求:
      此方法的默认实现会抛出UnsupportedOperationException。通过HttpClient.newBuilder()获取的Builder提供了允许设置本地地址的此方法的实现。
      参数:
      localAddr - 套接字的本地地址。可以为null。
      返回:
      此构建器
      抛出:
      UnsupportedOperationException - 如果此构建器不支持配置本地地址或传递的localAddr不受此HttpClient实现支持。
      自 JDK 版本:
      19

    • build

      HttpClient build()
      返回根据此构建器的当前状态构建的新HttpClient。
      实现要求:
      如果本地地址是非空地址并且安装了安全管理器，则此方法调用checkListen来检查调用者是否具有绑定到该本地地址所需的权限。
      返回值:
      一个新的HttpClient
      抛出:
      UncheckedIOException - 如果实现所需的底层IO资源无法分配，则可能会抛出。例如，如果实现需要一个Selector，并且由于缺乏必要资源而打开失败。
      SecurityException - 如果安装了安全管理器并且安全管理器的checkListen方法禁止绑定到给定地址。