High level HTTP Client and WebSocket API.
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.
The HTTP Client API provides non-blocking request and response semantics
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
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.
The HTTP Client API will be in the new
java.net.http module, which
exports a single package of the same name,
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
BodyPublisherthat implement various useful publishers, such as publishing the request body from a String, or from a file.
HttpResponseis 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
BodyHandlerinterface allows inspection of the response code and headers, before the actual response body is received, and is responsible for creating the response
HttpResponse.BodyHandlers- Predefined implementations of
BodyHandlerthat implement various useful handlers, such as handling the response body as a String, or streaming the response body to a file.
BodySubscriberconsumes the actual response body bytes and converts them into a higher-level Java type.
HttpResponse.BodySubscribers- Predefined implementations of
BodySubscriberthat 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:
Removal of the incubating API
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.