- 封装类:
-
HttpClient
通过调用newBuilder
来创建构建器。每个setter方法修改构建器的状态并返回相同的实例。构建器不是线程安全的,不应在多个线程中并发使用,除非进行外部同步。
- 自 JDK 版本:
- 11
-
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionauthenticator
(Authenticator authenticator) 设置用于HTTP身份验证的认证器。build()
返回根据此构建器的当前状态构建的新HttpClient
。connectTimeout
(Duration duration) 设置此客户端的连接超时持续时间。cookieHandler
(CookieHandler cookieHandler) 设置一个cookie处理程序。设置用于异步和依赖任务的执行程序。followRedirects
(HttpClient.Redirect policy) 指定请求是否会自动遵循服务器发出的重定向。default HttpClient.Builder
localAddress
(InetAddress localAddr) 在发送请求时,将套接字绑定到此本地地址。priority
(int priority) 设置从此客户端发送的任何HTTP/2请求的默认优先级。proxy
(ProxySelector proxySelector) 设置一个ProxySelector
。sslContext
(SSLContext sslContext) 设置一个SSLContext
。sslParameters
(SSLParameters sslParameters) 设置一个SSLParameters
。version
(HttpClient.Version version) 在可能的情况下请求特定的HTTP协议版本。
-
Field Details
-
NO_PROXY
一个总是返回Proxy.NO_PROXY
的代理选择器,表示直接连接。这是一个方便的对象,可以传递给
proxy(ProxySelector)
,以构建使用无代理的HttpClient
实例。
-
-
Method Details
-
cookieHandler
设置一个cookie处理程序。- 参数:
-
cookieHandler
- cookie处理程序 - 返回:
- 此构建器
-
connectTimeout
设置此客户端的连接超时持续时间。在需要建立新连接的情况下,如果连接无法在给定的
持续时间
内建立,则HttpClient::send
会抛出一个HttpConnectTimeoutException
,或者HttpClient::sendAsync
会异常完成,带有一个HttpConnectTimeoutException
。如果不需要建立新连接,例如如果可以重用来自先前请求的连接,则此超时持续时间不起作用。- 参数:
-
duration
- 允许建立底层连接的持续时间 - 返回:
- 此构建器
- 抛出:
-
IllegalArgumentException
- 如果持续时间为非正数
-
sslContext
- 参数:
-
sslContext
- SSL上下文 - 返回:
- 此构建器
-
sslParameters
设置一个SSLParameters
。如果在构建之前未调用此方法,则新构建的客户端将使用默认的、特定于实现的一组参数。
一些由HTTP客户端实现内部使用的参数(例如应用程序协议列表)不应该由调用者设置,因为它们可能会被忽略。给定对象的内容将被复制。
- 参数:
-
sslParameters
- SSL参数 - 返回:
- 此构建器
-
executor
设置用于异步和依赖任务的执行程序。如果在构建之前未调用此方法,则为每个新构建的
HttpClient
创建一个默认执行程序。- 实现说明:
- 默认执行程序使用线程池,带有自定义线程工厂。如果已安装安全管理器,则线程工厂创建的线程将以没有权限的访问控制上下文运行。
- 参数:
-
executor
- 执行程序 - 返回:
- 此构建器
-
followRedirects
- 参数:
-
policy
- 重定向策略 - 返回:
- 此构建器
-
version
在可能的情况下请求特定的HTTP协议版本。如果在构建之前未调用此方法,则新构建的客户端将优先选择HTTP/2。
如果设置为HTTP/2,则每个请求将尝试升级到HTTP/2。如果升级成功,则对此请求的响应将使用HTTP/2,并且所有后续请求和响应到相同的源服务器将使用HTTP/2。如果升级失败,则响应将使用HTTP/1.1处理。
- 实现说明:
- 约束也可能影响协议版本的选择。例如,如果通过代理请求HTTP/2,并且实现不支持此模式,则可能会使用HTTP/1.1
- 参数:
-
version
- 请求的HTTP协议版本 - 返回:
- 此构建器
-
priority
设置从此客户端发送的任何HTTP/2请求的默认优先级。提供的值必须在1
和256
之间(包括边界值)。- 参数:
-
priority
- 优先级权重 - 返回:
- 此构建器
- 抛出:
-
IllegalArgumentException
- 如果给定的优先级超出范围
-
proxy
设置一个ProxySelector
。- API说明:
-
ProxySelector::of
提供一个为所有请求使用单个代理的ProxySelector
。可以通过ProxySelector.getDefault()
检索系统范围的代理选择器。 - 实现说明:
-
如果在构建之前未调用此方法,则新构建的客户端将使用默认代理选择器,通常适用于客户端应用程序。默认代理选择器支持与代理设置相关的一组系统属性。可以通过在构建之前提供显式代理选择器(例如
NO_PROXY
或由ProxySelector::of
返回的代理选择器)来禁用此默认行为。 - 参数:
-
proxySelector
- 代理选择器 - 返回:
- 此构建器
-
authenticator
设置用于HTTP身份验证的认证器。- 参数:
-
authenticator
- 认证器 - 返回:
- 此构建器
-
localAddress
在发送请求时,为创建连接将套接字绑定到此本地地址。如果未设置本地地址或将
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
方法禁止绑定到给定地址。
-