- java.lang.Object
-
- java.net.http.HttpClient
-
public abstract class HttpClient extends Object
HTTP客户端。一个
HttpClient
可用于发送requests并检索其responses 。HttpClient
是通过builder
创建的。 构建器可用于配置每个客户端状态,如:首选协议版本(HTTP / 1.1或HTTP / 2),是否遵循重定向,代理,身份验证器等。一旦构建,HttpClient
是不可变的,并且可用于发送多个请求。HttpClient
为通过它发送的所有请求提供配置信息和资源共享。必须为每个发送的
HttpRequest
提供BodyHandler
。BodyHandler
确定如何处理响应主体(如果有)。 收到HttpResponse
后 ,标题,响应代码和正文(通常)可用。 是否已读取响应正文字节取决于响应正文的类型T
。请求可以同步或异步发送:
-
send(HttpRequest, BodyHandler)
阻止,直到请求已发送并已收到响应。 -
sendAsync(HttpRequest, BodyHandler)
发送请求并异步接收响应。sendAsync
方法立即返回CompletableFuture
<HttpResponse
>。 响应可用时,CompletableFuture
完成。 返回的CompletableFuture
可以以不同的方式组合以声明多个异步任务之间的依赖关系。
同步示例
HttpClient client = HttpClient.newBuilder() .version(Version.HTTP_1_1) .followRedirects(Redirect.NORMAL) .connectTimeout(Duration.ofSeconds(20)) .proxy(ProxySelector.of(new InetSocketAddress("proxy.example.com", 80))) .authenticator(Authenticator.getDefault()) .build(); HttpResponse<String> response = client.send(request, BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body());
异步示例
HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://foo.com/")) .timeout(Duration.ofMinutes(2)) .header("Content-Type", "application/json") .POST(BodyPublishers.ofFile(Paths.get("file.json"))) .build(); client.sendAsync(request, BodyHandlers.ofString()) .thenApply(HttpResponse::body) .thenAccept(System.out::println);
如果存在安全管理器,则由HTTP客户端的发送方法执行安全检查。 访问目标服务器和代理服务器(如果已配置)需要适当的
URLPermission
。 访问代理所需的URLPermission
的形式具有method
参数"CONNECT"
(用于所有类型的代理)和URL
形式的字符串"socket://host:port"
,其中主机和端口指定代理的地址。- Implementation Note:
-
如果尚未为
HttpClient
设置显式executor ,并且已安装安全管理器,则默认执行程序将在未授予权限的上下文中执行异步和从属任务。 自request body publishers , response body handlers , response body subscribers和WebSocket Listeners ,如果执行需要权限的操作,应该在适当的做privileged context 。 - 从以下版本开始:
- 11
-
-
-
嵌套类汇总
嵌套类 变量和类型 类 描述 static interface
HttpClient.Builder
建筑师HTTP Clients 。static class
HttpClient.Redirect
定义自动重定向策略。static class
HttpClient.Version
HTTP协议版本。
-
构造方法摘要
构造方法 变量 构造器 描述 protected
HttpClient()
创建一个HttpClient。
-
方法摘要
所有方法 静态方法 实例方法 抽象方法 具体的方法 变量和类型 方法 描述 abstract Optional<Authenticator>
authenticator()
返回包含此客户端上设置的Optional
的Optional 。abstract Optional<Duration>
connectTimeout()
返回包含此客户端的 连接超时持续时间的Optional
。abstract Optional<CookieHandler>
cookieHandler()
返回一个Optional
包含此客户端的CookieHandler
。abstract Optional<Executor>
executor()
返回一个Optional
包含此客户端的Executor
。abstract HttpClient.Redirect
followRedirects()
返回此客户端的以下重定向策略。static HttpClient.Builder
newBuilder()
创建一个新的HttpClient
构建器。static HttpClient
newHttpClient()
返回具有默认设置的新HttpClient
。WebSocket.Builder
newWebSocketBuilder()
创建一个新的WebSocket
构建器(可选操作)。abstract Optional<ProxySelector>
proxy()
返回包含提供给此客户端的Optional
的ProxySelector
。abstract <T> HttpResponse<T>
send(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler)
使用此客户端发送给定请求,必要时阻止获取响应。abstract <T> CompletableFuture<HttpResponse<T>>
sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler)
使用此客户端与给定的响应正文处理程序异步发送给定的请求。abstract <T> CompletableFuture<HttpResponse<T>>
sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler, HttpResponse.PushPromiseHandler<T> pushPromiseHandler)
使用此客户端与给定的响应正文处理程序和推送承诺处理程序异步发送给定请求。abstract SSLContext
sslContext()
返回此客户端的SSLContext
。abstract SSLParameters
sslParameters()
返回此客户端的副本SSLParameters
。abstract HttpClient.Version
version()
返回此客户端的首选HTTP协议版本。
-
-
-
方法详细信息
-
newHttpClient
public static HttpClient newHttpClient()
返回具有默认设置的新HttpClient
。相当于
newBuilder().build()
。默认设置包括:“GET”请求方法,的偏好HTTP/2的重定向策略NEVER ,该default proxy selector和default SSL context 。
- Implementation Note:
-
在构造
HttpClient
实例时检索系统范围的默认值。 例如,通过调用ProxySelector.setDefault(ProxySelector)
或SSLContext.setDefault(SSLContext)
构建HttpClient
实例后更改系统范围的值对已构建的实例没有影响。 - 结果
- 一个新的HttpClient
-
newBuilder
public static HttpClient.Builder newBuilder()
创建一个新的HttpClient
构建器。- 结果
-
HttpClient.Builder
-
cookieHandler
public abstract Optional<CookieHandler> cookieHandler()
返回一个Optional
包含此客户端的CookieHandler
。 如果在此客户端的构建器中未设置CookieHandler
,则Optional
为空。- 结果
-
Optional
包含此客户端的CookieHandler
-
connectTimeout
public abstract Optional<Duration> connectTimeout()
返回包含此客户端的连接超时持续时间的Optional
。 如果connect timeout duration没有在客户端的建设者设置,那么Optional
是空的。- 结果
-
包含此客户端的连接超时持续时间的
Optional
-
followRedirects
public abstract HttpClient.Redirect followRedirects()
返回此客户端的以下重定向策略。 未指定重定向策略的构建器构建的客户端的默认值为NEVER
。- 结果
- 此客户端遵循重定向设置
-
proxy
public abstract Optional<ProxySelector> proxy()
返回包含提供给此客户端的Optional
的ProxySelector
。 如果在此客户端的构建器中未设置代理选择器,则Optional
为空。即使此方法可能返回空的可选项,
HttpClient
仍可能具有用于发送HTTP请求的非公开default proxy selector 。- 结果
-
包含提供给此客户端的代理选择器的
Optional
。
-
sslContext
public abstract SSLContext sslContext()
返回此客户端的SSLContext
。如果没有
SSLContext
在这个客户端的建设者设置,那么default context返回。- 结果
- 这个客户端的SSLContext
-
sslParameters
public abstract SSLParameters sslParameters()
返回此客户端的副本SSLParameters
。如果在客户端的构建器中未设置
SSLParameters
,则返回客户端将使用的特定于实现的默认参数集。- 结果
-
这个客户的
SSLParameters
-
authenticator
public abstract Optional<Authenticator> authenticator()
返回包含此客户端上设置的Optional
的Optional 。 如果客户端的构建器中未设置Authenticator
,则Optional
为空。- 结果
-
Optional
包含此客户端的Authenticator
-
version
public abstract HttpClient.Version version()
返回此客户端的首选HTTP协议版本。 默认值为HttpClient.Version.HTTP_2
- Implementation Note:
- 约束也可能影响协议版本的选择。 例如,如果通过代理请求HTTP / 2,并且如果实现不支持此模式,则可以使用HTTP / 1.1
- 结果
- 请求的HTTP协议版本
-
executor
public abstract Optional<Executor> executor()
返回一个Optional
包含此客户端的Executor
。 如果在客户端的构建器中未设置Executor
,则Optional
为空。即使此方法可能返回空可选,
HttpClient
仍可能具有未公开的default executor ,用于执行异步和从属任务。- 结果
-
Optional
包含此客户端的Executor
-
send
public abstract <T> HttpResponse<T> send(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler) throws IOException, InterruptedException
使用此客户端发送给定请求,必要时阻止获取响应。 返回的HttpResponse
<T>
包含响应状态,标题和正文(由给定的响应正文处理程序处理)。- 参数类型
-
T
- 响应正文类型 - 参数
-
request
- 请求 -
responseBodyHandler
- 响应正文处理程序 - 结果
- 响应
- 异常
-
IOException
- 如果发送或接收时发生I / O错误 -
InterruptedException
- 如果操作中断 -
IllegalArgumentException
- 如果request
参数不是可以按照HttpRequest.Builder
指定的有效构建的请求 。 -
SecurityException
- 如果已安装安全管理器并且它拒绝给定请求中的URLaccess
,或者如果配置了代理,则拒绝代理。 有关详细信息,请参阅security checks 。
-
sendAsync
public abstract <T> CompletableFuture<HttpResponse<T>> sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler)
使用此客户端与给定的响应正文处理程序异步发送给定的请求。相当于:
sendAsync(request, responseBodyHandler, null)
。- 参数类型
-
T
- 响应正文类型 - 参数
-
request
- 请求 -
responseBodyHandler
- 响应正文处理程序 - 结果
-
CompletableFuture<HttpResponse<T>>
- 异常
-
IllegalArgumentException
- 如果request
参数不是可以按照HttpRequest.Builder
指定的有效构建的请求 。
-
sendAsync
public abstract <T> CompletableFuture<HttpResponse<T>> sendAsync(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler, HttpResponse.PushPromiseHandler<T> pushPromiseHandler)
使用此客户端与给定的响应正文处理程序和推送承诺处理程序异步发送给定请求。如果成功完成,返回的可完成的未来将以
HttpResponse
<T>
完成,其中包含响应状态,标题和正文(由给定的响应正文处理程序处理)。收到的Push promises (如有)由给定的
pushPromiseHandler
处理。 一个null
价值pushPromiseHandler
拒绝任何推许。返回的可完成的未来异常完成:
-
IOException
- 如果发送或接收时发生I / O错误 -
SecurityException
- 如果已安装安全管理器并且它拒绝给定请求中的URLaccess
,或者如果配置了代理,则拒绝代理。 有关详细信息,请参阅security checks 。
- 参数类型
-
T
- 响应正文类型 - 参数
-
request
- 请求 -
responseBodyHandler
- 响应正文处理程序 -
pushPromiseHandler
- 推送承诺处理程序,可以为null - 结果
-
CompletableFuture<HttpResponse<T>>
- 异常
-
IllegalArgumentException
- 如果request
参数不是可以按照HttpRequest.Builder
的指定有效构建的请求 。
-
-
newWebSocketBuilder
public WebSocket.Builder newWebSocketBuilder()
创建一个新的WebSocket
构建器(可选操作)。例
HttpClient client = HttpClient.newHttpClient(); CompletableFuture<WebSocket> ws = client.newWebSocketBuilder() .buildAsync(URI.create("ws://websocket.example.com"), listener);
通过使用自定义
HttpClient
可以更好地控制WebSocket打开握手。例
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);
- 实现要求:
-
此方法的默认实现抛出
UnsupportedOperationException
。 通过newHttpClient()
或newBuilder()
获得的客户返回WebSocket
建造商。 - Implementation Note:
-
使用它创建的构建器和
WebSocket
都以非阻塞方式运行。 也就是说,他们的方法在返回CompletableFuture
之前不会阻止。 异步任务在此HttpClient
的执行程序中执行。当
CompletionStage
返回的CompletionStage完成时,WebSocket
将发送一条Close消息,该消息具有与接收消息相同的代码和空原因。 - 结果
-
WebSocket.Builder
- 异常
-
UnsupportedOperationException
- 如果此HttpClient
不提供WebSocket支持
-
-