JEP 321: HTTP Client (Standard)

OwnerChris Hegarty
Created2017/06/08 11:46
Updated2017/12/14 15:07
TypeFeature
StatusCandidate
Componentcore-libs / java.net
ScopeSE
Discussionnet dash dev at openjdk dot java dot net
EffortM
DurationM
Priority2
Reviewed byAlan Bateman, Brian Goetz
Endorsed byBrian Goetz
Issue8181784

Summary

Standardize the incubated HTTP Client API introduced in JDK 9, via JEP 110, and updated in JDK 10.

Goals

In addition to the goals of JEP 110, this JEP will:

Motivation

The motivation of this JEP remains the same as that of the motivation of JEP 110.

Description

This JEP proposes to standardize the HTTP Client API that was introduced as an incubating API in JDK 9 and updated in JDK 10. The incubating 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 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.

While incubating in JDK 9 and JDK 10, the implementation has been almost completely rewritten. The implementation is now completely asynchronous (the previous HTTP/1.1 implementation was blocking). Use of the RX Flow concept has been pushed down into the implementation, which eliminated many of the original custom concepts needed to support HTTP/2. The flow of data can now be more easily traced, from the user-level request publishers and response subscribers all the way down to the underlying socket. This significantly reduces the number of concepts and complexity in the code, and maximizes the possibility of reuse between HTTP/1.1 and HTTP/2.

Proposal for the standard module name: java.net.httpclient. Proposal for the standard package name: java.net.http.

Further specifics on the API can be found in JEP 110.

Testing

Existing tests for the incubated API will need to be updated to use the new standard API. Additional tests will be added to cover all scenarios supported, specifically the upgrade and downgrade between HTTP/1.1 and HTTP/2.

Risks and Assumptions

Code that currently depends upon the incubated HTTP Client API will need to be updated, at the very minimum to change its package imports. This is no different than for any other incubated feature. Code depending upon incubating modules already receives an appropriate warning at both compile time and run time.