JEP 110: HTTP/2 Client (Incubator)

OwnerMichael McMahon
TypeFeature
ScopeJDK
StatusClosed / Delivered
Release9
Componentcore-libs / java.net
Discussionnet dash dev at openjdk dot java dot net
EffortXL
DurationXL
Relates toJEP 244: TLS Application-Layer Protocol Negotiation Extension
JEP 321: HTTP Client API
Reviewed byAlan Bateman
Endorsed byBrian Goetz
Created2014/05/12 16:26
Updated2022/05/31 16:17
Issue8042950

Summary

Define a new HTTP client API that implements HTTP/2 and WebSocket, and can replace the legacy HttpURLConnection API. The API will be delivered as an incubator module, as defined in JEP 11, with JDK 9. This implies:

Motivation

The existing HttpURLConnection API and its implementation have numerous problems:

Goals

Non-Goals

This API is intended to eventually replace the HttpURLConnection API for new code, but we do not intend immediately to re-implement the old API using the new API. This may happen as future work.

Some requirements were considered in earlier versions of this JEP for JDK 8, but they are being left out in order to keep the API as simple as possible:

Some of these requirements, e.g., connection caching, will become less important with the gradual adoption of HTTP/2.

Description

Some prototyping work has been done for JDK 9 in which separate classes were defined for the HTTP client, requests, and responses. The builder pattern was used to separate mutable entities from the immutable products. A synchronous blocking mode is defined for sending and receiving and an asynchronous mode built on java.util.concurrent.CompletableFuture is also defined.

The prototype was built on NIO SocketChannels with asynchronous behavior implemented with Selectors and externally provided ExecutorServices.

The prototype implementation was standalone, i.e., the existing stack was not changed so as to ensure compatibility and allow a phased approach in which not all functionality must be supported at the start.

The prototype API also included:

The part of the API most likely to need further work is in the support of HTTP/2 multi responses (server push) and HTTP/2 configuration. The prototype implementation supports almost all of HTTP/1.1 but not yet HTTP/2.

HTTP/2 proxying will be implemented in a following change.

Alternatives

A number of existing HTTP client APIs and implementations exist, e.g., Jetty and the Apache HttpClient. Both of these are both rather heavy-weight in terms of the numbers of packages and classes, and they don't take advantage of newer language features such as lambda expressions.

Testing

The internal HTTP server will provide a suitable basis for regression and TCK tests. Functional tests could use that also, but they may need to test against real HTTP servers.