Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8197565

HTTP Client API

    XMLWordPrintable

    Details

    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      New API, no impact on existing code.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      High level HTTP Client and WebSocket API.

      Problem

      This CSR proposes to standardize the HTTP Client API that was introduced as an incubating API in JDK 9 ( JEP 110 ) and updated in JDK 10. The incubated API has received a number of rounds of feedback that have resulted in significant improvements, but at a high level it remains largely the same.

      Solution

      The HTTP Client API provides non-blocking request and response semantics through CompletableFutures, which can be chained to trigger dependent actions. Back-pressure and flow-control of request and response bodies is provided for via the Platform's reactive-streams support in the java.util.concurrent.Flow API.

      An introduction to the API and example usage are useful resources to quickly familiarize reviewers / readers with the API. The code snippets in both of these resources demonstrate usage to perform common tasks.

      Specification

      The HTTP Client API will be in the new java.net.http module, which exports a single package of the same name, java.net.http.

      High-level API types and their function:

      • HttpClient - An HttpClient can be used to send requests and retrieve their responses.
      • HttpRequest - An immutable request containing the request URI, headers, and optional body.
      • HttpRequest.BodyPublisher - A BodyPublisher converts high-level Java objects into a flow of byte buffers suitable for sending as a request body.
      • HttpRequest.BodyPublishers - Predefinded implementations of BodyPublisher that implement various useful publishers, such as publishing the request body from a String, or from a file.
      • HttpResponse - An HttpResponse is made available when the response status code and headers have been received, and typically after the response body has also been completely received.
      • HttpResponse.BodyHandler - Must be supplied for each HttpRequest sent. The BodyHandler interface allows inspection of the response code and headers, before the actual response body is received, and is responsible for creating the response BodySubscriber.
      • HttpResponse.BodyHandlers - Predefined implementations of BodyHandler that implement various useful handlers, such as handling the response body as a String, or streaming the response body to a file.
      • HttpResponse.BodySubscriber - The BodySubscriber consumes the actual response body bytes and converts them into a higher-level Java type.
      • HttpResponse.BodySubscribers - Predefined implementations of BodySubscriber that implement various useful subscribers, such as converting the response body bytes into a String, or streaming the bytes to a file.
      • WebSocket - A WebSocket client providing low-level access to sending and receiving WebSocket messages.

      The remaining API types can be seen the attached / linked javadoc.

      On-line link to the javadoc:

      http://cr.openjdk.java.net/~chegar/httpclient/01/javadoc/api/java/net/http/package-summary.html

      Removal of the incubating API

      The jdk.incubator.httpclient module and ALL public types in the jdk.incubator.http package will be remove. This constitutes a complete removal of the incubating API added by JEP 110.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              chegar Chris Hegarty
              Reporter:
              chegar Chris Hegarty
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: