Summary

Idle HTTP/2 connections will be closed by the java.net.http.HttpClient if they remain idle for too long, in the same way that HTTP/1.1 connections are. The value of the existing jdk.httpclient.keepalive.timeout property which was used to configure the keep-alive time of HTTP/1.1 connections now also configures the HTTP/2 connections idle timeout.

Problem

There currently does not exist a means to close an idle HTTP/2 connection when using the HttpClient. This means that an HTTP/2 connection will remain open until it is closed by the peer. With this change if an application configures a maximum idle connection timeout, it will apply both to HTTP/1.1 connections and HTTP/2 connections.

Solution

The default keep alive timeout used by the java.net.http.HttpClient for HTTP/1.1 connections now also applies to HTTP/2 connections. If an application configures a system-wide idle connection timeout by specifying a jdk.httpclient.keepalive.timeout property on the command line, the value will apply to all connections created by the java.net.http.HttpClient regardless of the underlying protocol. An application can now specify a timeout duration, in seconds, of how long a connection is permitted to be idle, regardless of the underlying protocol. The value of the property now applies both to HTTP/1.1 and HTTP/2 connections.

Additionally, the jdk.httpclient.keepalive.timeout.h2 property can be used to a configure a timeout value to close idle HTTP/2 connections within an interval that is different from the value of the the jdk.httpclient.keepalive.timeout property. An idle HTTP/2 connection can be defined as one which maintains no open and active streams aside from the control/connection stream (stream 0).

When no value is passed for the jdk.httpclient.keepalive.timeout or jdk.httpclient.keepalive.timeout.h2 properties, a default idle connection timeout of 1200s will be used for all client connections regardless of the protocol version.

Specification

The jdk.httpclient.keepalive.timeout property is documented in the Java Core Libraries Developer's Guide

This change requires updates to be made to the Java SE, Java Core Libraries Developer's Guide section on Java Networking. The current entry for jdk.httpclient.keepalivetimeout should be changed to reflect its new effects. A suggested replacement for the current description of the property would be "Configures a system-wide idle connection timeout interval, in seconds, before a connection is closed regardless of underlying protocol".

In addition, a new entry is also required in the networking property list for the new property jdk.httpclient.keepalive.timeout.h2. A description for this would be "Configures an idle connection timeout interval for HTTP/2 exclusively. If a jdk.httpclient.keepalive.timeout property is specified, this can be used to override the value of that property for HTTP/2 only." For the default value column, the same value of 1200 seconds is used.

The change in behavior for the jdk.httpclient.keepalive.timeout, as well as the new jdk.httpclient.keepalive.timeout.h2 property, will also be documented in the release notes.

Note that a separate issue, JDK-8296804 has been logged to generally document all properties supported by the JDK HttpClient implementation in the java.net.http module-info.