-
JEP
-
Resolution: Delivered
-
P2
-
Chris Hegarty
-
Feature
-
Open
-
SE
-
-
M
-
M
-
321
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:
- Take into account feedback received on the incubated API,
- Provide a standardized API, in the
java.net.http
package, based upon the incubated API, and - Remove the incubated API.
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 CompletableFuture
s, 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.
The module name and the package name of the standard API will be
java.net.http
.
Changes over what was incubated in JDK 10
The predefined implementation of
BodyPublisher
,BodyHandler
, andBodySubscriber
, created through static factory methods, have been moved out to separate non-instantiable utility factory classes, following the pluralized naming convention. This improves readability of these relatively small interfaces.The names of the static factory methods have also been updated along the following broad categories:
fromXxx
: Adapters from standard Subscriber, e.g. takes aFlow.Subscriber
returns aBodySubscriber
.ofXxx
: Factories that create a new pre-definedBody[Publisher|Handler|Subscriber]
that perform useful common tasks, such as handling the response body as a String, or streaming the body to a File.other: Combinators (takes a
BodySubscriber
returns aBodySubscriber
) and other useful operations.
A few
BodyHandler
s and correspondingBodySubscriber
s have been added, to improve usability in common scenarios:discard(Object replacement)
combined discarding/ignoring the response body and allowing a given replacement. Feedback has indicated that this could appear confusing. It has been removed and replaced with two separate handlers: 1)discarding()
, and 2)replacing(Object replacement)
.Added
ofLines()
that returns aBodyHandler<Stream<String>>
, to support streaming of response body as aStream
of lines, line by line. Provides similar semantics to that ofBufferedReader.lines()
.Added
fromLineSubscriber​
, that supports adaptation of response body to aFlow.Subscriber
ofString
lines.Added
BodySubscriber.mapping
for general purpose mapping from one response body type to another.
The push promise support has been re-worked to reduce its impact on the API and bring it more in line with regular request/responses. Specifically, the
MultiSubscriber
andMultiResultMap
have been removed. Push promises are now handled through a functional interface,PushPromiseHandler
, that is optionally given during a send operation.The
HttpClient.Redirect
policy has been simplified, by replacingSAME_PROTOCOL
andSECURE
policies, withNORMAL
. It has been observed that the previously namedSECURE
was not really appropriately named and should be renamed toNORMAL
, since it will likely be suitable for most normal cases. Given the newly named, aforementioned,NORMAL
,SAME_PROTOCOL
appears oddly named, possibly confusing, and not likely to be used.WebSocket.MessagePart
has been removed. This enum was used on the receiving side to indicate whether the delivery of a message is complete, or not. It is asymmetric with the sending side, which uses a simple boolean for this purpose. Additionally, it has been observed that handling received messages with a simple boolean significantly reduces and simplifies the receiving code logic. Determination of messages being delivered as aWHOLE
, one of the benefits and the main purposes for the aforementionedMessagePart
, has proved to not carry its own weight.
Further specifics on the API can be found in JEP 110, at the latest API javadoc, or the networking group's JDK HTTP Client page.
Testing
Existing tests for the incubated API will 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.
- relates to
-
JDK-8042950 JEP 110: HTTP/2 Client (Incubator)
- Closed
-
JDK-8251312 HttpClient send throws InterruptedException when interrupted but does not cancel request
- Closed
-
JDK-8276996 Add an HttpRequest.Builder.HEAD method to build a HEAD request.
- Closed
-
JDK-8286583 Add ability to bind to specific local address to HTTP client
- Closed
-
JDK-8304165 Support closing the HttpClient by making it auto-closable
- Closed
-
JDK-8291976 HTTP/3 for the HTTP Client API
- Submitted
1.
|
HTTP Client implementation | Resolved | Chris Hegarty | ||
2.
|
Release Note: JEP 321: HTTP Client (Standard) | Closed | Chris Hegarty |