Module  jdk.incubator.httpclient
软件包  jdk.incubator.http

Class HttpRequest


  • public abstract class HttpRequest
extends Object
    表示可以发送到服务器的一个HTTP请求。
    Incubating Feature.将在以后的版本中删除。

    HttpRequest是从HttpRequest builder s。 HttpRequest通过致电HttpRequest.newBuilder获得建设者。 一个请求的URI ，头和身都可以设置。 请求体通过提供HttpRequest.BodyProcessor供给到对象DELETE ， POST或PUT方法。 GET不用身体。 一旦所有必需的参数都在构建器设置， HttpRequest.Builder.build()被称为返回HttpRequest 。 建筑商也可以多次复制和修改，以构建一些参数不同的多个相关请求。

    两个简单的示例HTTP交互如下所示： 

       HttpClient client = HttpClient.newHttpClient(); // GET HttpResponse<String> response = client.send( HttpRequest .newBuilder(new URI("http://www.foo.com/")) .headers("Foo", "foovalue", "Bar", "barvalue") .GET() .build(), BodyHandler.asString() ); int statusCode = response.statusCode(); String body = response.body(); // POST HttpResponse<Path> response = client.send( HttpRequest .newBuilder(new URI("http://www.foo.com/")) .headers("Foo", "foovalue", "Bar", "barvalue") .POST(BodyProcessor.fromString("Hello world")) .build(), BodyHandler.asFile(Paths.get("/path")) ); int statusCode = response.statusCode(); Path body = response.body(); // should be "/path"

    发送请求，并通过在HttpClient中调用以下方法之一获得响应。

    一旦接收到HttpResponse ，标题，响应代码和主体（通常）都可用。 身体是否被读取取决于响应体的类型<T> 。 见下文。

    有关同步与异步使用的讨论，请参见下文。

    请求机构

    请求主体使用下列HttpRequest.BodyProcessor中提供的请求处理器实现之一发送 ，否则可以使用自定义实现。

    反应机构

    回应机构在两个层面处理。 发送请求时，指定响应主体处理程序。 这是一个函数（ HttpResponse.BodyHandler ），一旦接收到这个函数，它将被响应状态代码和头部调用。 然后，该函数应该返回一个HttpResponse.BodyProcessor <T> ，然后将其用于读取响应主体转换成T的一个实例在此之后，响应在变得可用HttpResponse和HttpResponse.body()然后可以被调用以获得身体。 有些实现两者的使用实例HttpResponse.BodyProcessor和HttpResponse.BodyHandler中提供HttpResponse ：

    一些预定义的身体处理程序

    多重反应

    使用HTTP / 2，服务器可以将主响应和零个或多个附加响应（称为服务器推送）发送到客户端发起的请求。 这些是使用一个叫做HttpResponse.MultiProcessor的特殊响应处理器处理的。

    阻塞/异步行为和线程使用

    有两种请求发送方式： 同步和异步 。 HttpClient.send(HttpRequest, HttpResponse.BodyHandler)阻塞调用线程，直到发送请求并收到响应。

    HttpClient.sendAsync(HttpRequest, HttpResponse.BodyHandler)是异步的，并立即返回一个CompletableFuture < HttpResponse >，当该对象完成（在后台线程中）时，已收到响应。

    HttpClient.sendAsync(HttpRequest,HttpResponse.MultiProcessor)是多响应的变体，也是异步的。

    CompletableFuture可以以不同的方式组合，以声明几个异步任务之间的依赖关系，同时允许最大程度的并行性被利用。

    安全检查

    如果存在安全管理员，则通过发送方法进行安全检查。 需要URLPermission或SocketPermission才能访问所使用的任何目的地源服务器和代理服务器。 URLPermission S的关系的政策文件超过首选SocketPermission给出的范围更有限小号URLPermission 。 权限总是隐含地授予系统的默认代理。 用于访问代理的URLPermission表单使用方法参数为"CONNECT" （用于各种代理）和一个形式为"socket://host:port"的url字符串，其中host和port指定代理的地址。

    例子 

       HttpClient client = HttpClient .newBuilder() .build(); HttpRequest request = HttpRequest .newBuilder(new URI("http://www.foo.com/")) .POST(BodyProcessor.fromString("Hello world")) .build(); HttpResponse<Path> response = client.send(request, BodyHandler.asFile(Paths.get("/path"))); Path body = response.body();

    异步例子

    上面的例子将异步工作，如果(HttpRequest, HttpResponse.BodyHandler) sendAsync来代替send在这种情况下返回的对象是CompletableFuture <HttpResponse>代替HttpResponse 。 以下示例显示可以异步发送多个请求。 它还显示了如何使用CompletableFuture中的许多方法之一轻松链接从属异步操作（接收响应和接收响应体）。 

       // fetch a list of target URIs asynchronously and store them in Files. List<URI> targets = ... List<CompletableFuture<File>> futures = targets .stream() .map(target -> client .sendAsync( HttpRequest.newBuilder(target) .GET() .build(), BodyHandler.asFile(Paths.get("base", target.getPath()))) .thenApply(response -> response.body()) .thenApply(path -> path.toFile())) .collect(Collectors.toList()); // all async operations waited for here CompletableFuture.allOf(futures.toArray(new CompletableFuture<?>[0])) .join(); // all elements of futures have completed and can be examined. // Use File.exists() to check whether file was successfully downloaded

    除非另有说明，否则null参数值将导致此类的方法抛出NullPointerException 。

    从以下版本开始：
    9

    • 构造方法详细信息

      • HttpRequest

        protected HttpRequest​()
        创建一个HttpRequest。

    • 方法详细信息

      • newBuilder

        public static HttpRequest.Builder newBuilder​()
        创建一个 HttpRequest构建器。
        结果
        一个新的请求生成器

      • bodyProcessor

        public abstract Optional<HttpRequest.BodyProcessor> bodyProcessor​()
        返回一个Optional其中包含HttpRequest.BodyProcessor这个请求。 如果在请求的构建器中没有设置BodyProcessor ，则Optional为空。
        结果
        一个 Optional包含该请求的 BodyProcessor

      • method

        public abstract String method​()
        返回此请求的请求方法。 如果未明确设置，任何请求的默认方法为“GET”。
        结果
        这个请求的方法

      • duration

        public abstract Duration duration​()
        返回此请求的持续时间。
        结果
        这要求持续时间

      • expectContinue

        public abstract boolean expectContinue​()
        返回此请求的 expect continue 设置。
        结果
        此请求期望继续设置

      • uri

        public abstract URI uri​()
        返回此请求的请求 URI 。
        结果
        这个请求的URI

      • version

        public abstract Optional<HttpClient.Version> version​()
        返回一个Optional其中包含将要为此HttpRequest请求的HTTP协议版本。 如果请求的构建器中未设置版本，则Optional为空。 在这种情况下，请求的版本将是发送HttpClient的版本 。 应查询相应的HttpResponse以确定实际使用的版本。
        结果
        HTTP协议版本

      • headers

        public abstract HttpHeaders headers​()
        此请求（或将要）发送的（用户可访问的）请求标头。
        结果
        这个请求的HttpHeaders

      • noBody

        public static HttpRequest.BodyProcessor noBody​()
        请求体处理程序，不发送请求体。
        结果
        一个BodyProcessor