HTTP Client API

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.