模块  java.net.http
软件包  java.net.http

Class HttpClient

  • public abstract class HttpClientextends Object
    HTTP客户端。

    一个HttpClient可用于发送requests并检索其responses 。 HttpClient是通过builder创建的。 构建器可用于配置每个客户端状态，如：首选协议版本（HTTP / 1.1或HTTP / 2），是否遵循重定向，代理，身份验证器等。一旦构建， HttpClient是不可变的，并且可用于发送多个请求。

    HttpClient为通过它发送的所有请求提供配置信息和资源共享。

    必须为每个发送的HttpRequest提供BodyHandler 。 BodyHandler确定如何处理响应主体（如果有）。 收到HttpResponse后 ，标题，响应代码和正文（通常）可用。 是否已读取响应正文字节取决于响应正文的类型T 。

    请求可以同步或异步发送：

    同步示例 

       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

    • 构造方法详细信息

      • HttpClient

        protected 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

      • 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 - 如果已安装安全管理器并且它拒绝给定请求中的URL access ，或者如果配置了代理，则拒绝代理。 有关详细信息，请参阅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支持