Defines the HTTP Client and WebSocket APIs.

System properties used by the java.net.http API

The following is a list of system networking properties used by the java.net.http client implementation in the JDK. Any properties below that take a numeric value assume the default value if given a string that does not parse as a number. Unless otherwise specified below, all values can be set in the conf/net.properties file. In all cases, values can be specified as system properties on the command line, in which case, any value in conf/net.properties is overridden. No guarantee is provided that property values can be set programatically with System.setProperty(). Other implementations of this API may choose not to support these properties.

• jdk.httpclient.allowRestrictedHeaders (default: see below)
  A comma-separated list of normally restricted HTTP header names that users may set in HTTP requests or by user code in HttpRequest instances. By default, the following request headers are not allowed to be set by user code: connection, content-length, expect, host, and upgrade. You can override this behavior with this property. The names are case-insensitive and whitespace is ignored. Note that this property is intended for testing and not for real-world deployments. Protocol errors or other undefined behavior are likely to occur when using this property. There may be other headers that are restricted from being set depending on the context. These restrictions cannot be overridden by this property.

• jdk.httpclient.bufsize (default: 16384 bytes or 16 kB)
  The capacity of internal ephemeral buffers allocated to pass data to and from the client, in bytes. Valid values are in the range [1, 2^14 (16384)]. If an invalid value is provided, the default value is used.

• jdk.httpclient.connectionPoolSize (default: 0)
  The maximum number of connections to keep in the HTTP/1.1 keep alive cache. A value of 0 means that the cache is unbounded.

• jdk.httpclient.connectionWindowSize (default: 2^26)
  The HTTP/2 client connection window size in bytes. Valid values are in the range [2^16-1, 2^31-1]. If an invalid value is provided, the default value is used. The implementation guarantees that the actual value will be no smaller than the stream window size, which can be configured through the jdk.httpclient.windowsize system property.

• jdk.httpclient.disableRetryConnect (default: false)
  Whether automatic retry of connection failures is disabled. If false, then retries are attempted (subject to the retry limit).

• jdk.httpclient.enableAllMethodRetry (default: false)
  Whether it is permitted to automatically retry non-idempotent HTTP requests.

• jdk.httpclient.enablepush (default: 1)
  Whether HTTP/2 push promise is enabled. A value of 1 enables push promise; a value of 0 disables it.

• jdk.httpclient.hpack.maxheadertablesize (default: 16384 or 16 kB)
  The HTTP/2 client maximum HPACK header table size in bytes.

• jdk.httpclient.qpack.decoderMaxTableCapacity (default: 0)
  The HTTP/3 client maximum QPACK decoder dynamic header table size in bytes.
  Setting this value to a positive number will allow HTTP/3 servers to add entries to the QPack decoder's dynamic table. When set to 0, servers are not permitted to add entries to the client's QPack encoder's dynamic table.

• jdk.httpclient.qpack.encoderTableCapacityLimit (default: 4096, or 4 kB)
  The HTTP/3 client maximum QPACK encoder dynamic header table size in bytes.
  Setting this value to a positive number allows the HTTP/3 client's QPack encoder to add entries to the server's QPack decoder's dynamic table, if the server permits it.

• jdk.httpclient.HttpClient.log (default: none)
  Enables high-level logging of various events through the Platform Logging API. The value contains a comma-separated list of any of the following items:

  • errors
  • requests
  • headers
  • content
  • frames
  • ssl
  • trace
  • channel
  • http3
  • quic
  
  You can append the frames item with a colon-separated list of any of the following items:
  • control
  • data
  • window
  • all
  
  You can append the quic item with a colon-separated list of any of the following items; packets are logged in an abridged form that only shows frames offset and length, but not content:
  • ack: packets containing ack frames will be logged
  • cc: information on congestion control will be logged
  • control: packets containing quic controls (such as frames affecting flow control, or frames opening or closing streams) will be logged
  • crypto: packets containing crypto frames will be logged
  • data: packets containing stream frames will be logged
  • dbb: information on direct byte buffer usage will be logged
  • ping: packets containing ping frames will be logged
  • processed: information on flow control (processed bytes) will be logged
  • retransmit: information on packet loss and recovery will be logged
  • timer: information on send task scheduling will be logged
  • all
  
  Specifying an item adds it to the HTTP client's log. For example, if you specify the following value, then the Platform Logging API logs all possible HTTP Client events:
  "errors,requests,headers,frames:control:data:window,ssl,trace,channel"
  Note that you can replace control:data:window with all. The name of the logger is "jdk.httpclient.HttpClient", and all logging is at level INFO. To debug issues with the quic protocol a good starting point is to specify quic:control:retransmit.

• jdk.httpclient.keepalive.timeout (default: 30)
  The number of seconds to keep idle HTTP connections alive in the keep alive cache. By default this property applies to HTTP/1.1, HTTP/2 and HTTP/3. The value for HTTP/2 and HTTP/3 can be overridden with the jdk.httpclient.keepalive.timeout.h2 and jdk.httpclient.keepalive.timeout.h3 properties respectively. The value specified for HTTP/2 acts as default value for HTTP/3. If the provided value is negative, the default value is used. A value of 0 is valid and has no special meaning other than the connection is closed when it becomes idle.

• jdk.httpclient.keepalive.timeout.h2 (default: see below)
  The number of seconds to keep idle HTTP/2 connections alive. If not set, or negative, then the jdk.httpclient.keepalive.timeout setting is used. A value of 0 is valid and has no special meaning other than the connection is closed when it becomes idle.

• jdk.httpclient.keepalive.timeout.h3 (default: see below)
  The number of seconds to keep idle HTTP/3 connections alive. If not set, or negative, then the jdk.httpclient.keepalive.timeout.h2 setting is used. A value of 0 is valid and has no special meaning other than the connection is closed when it becomes idle.

• jdk.httpclient.maxframesize (default: 16384 or 16kB)
  The HTTP/2 client maximum frame size in bytes. The server is not permitted to send a frame larger than this.

• jdk.httpclient.maxLiteralWithIndexing (default: 512)
  The maximum number of header field lines (header name and value pairs) that a client is willing to add to the HPack or QPACK Decoder dynamic table during the decoding of an entire header field section. This is purely an implementation limit. If a peer sends a field section or a set of QPACK instructions with encoding that exceeds this limit a ProtocolException will be raised. A value of zero or a negative value means no limit.

• jdk.httpclient.maxNonFinalResponses (default: 8)
  The maximum number of interim (non-final) responses that a client is prepared to accept on a request-response stream before the final response is received. Interim responses are responses with a status in the range [100, 199] inclusive. This is purely an implementation limit. If a peer sends a number of interim response that exceeds this limit before sending the final response, a ProtocolException will be raised. A value of zero or a negative value means no limit.

• jdk.httpclient.maxstreams (default: 100)
  The maximum number of HTTP/2 or HTTP/3 push streams that the client will permit servers to open simultaneously.

• jdk.httpclient.receiveBufferSize (default: operating system default)
  The HTTP client socket receive buffer size in bytes. Values less than or equal to zero are ignored.

• jdk.httpclient.redirects.retrylimit (default: 5)
  The maximum number of attempts to send a HTTP request when redirected or any failure occurs for any reason.

• jdk.httpclient.websocket.writeBufferSize (default: 16384 or 16kB)
  The buffer size used by the web socket implementation for socket writes.

• jdk.httpclient.windowsize (default: 16777216 or 16 MB)
  The HTTP/2 client stream window size in bytes. Valid values are in the range [2^14, 2^31-1]. If an invalid value is provided, the default value is used.

• jdk.httpclient.auth.retrylimit (default: 3)
  The number of attempts the Basic authentication filter will attempt to retry a failed authentication. The number of authentication attempts is always one greater than the retry limit, as the initial request does not count toward the retries.

• jdk.httpclient.sendBufferSize (default: operating system default)
  The HTTP client socket send buffer size in bytes. Values less than or equal to zero are ignored.

• jdk.internal.httpclient.disableHostnameVerification (default: false)
  If true (or set to an empty string), hostname verification in SSL certificates is disabled. This is a system property only and not available in conf/net.properties. It is provided for testing purposes only.

• jdk.http.auth.proxying.disabledSchemes (default: see conf/net.properties)
  A comma separated list of HTTP authentication scheme names, that are disallowed for use by the HTTP client implementation, for HTTP proxying.

• jdk.http.auth.tunneling.disabledSchemes (default: see conf/net.properties)
  A comma separated list of HTTP authentication scheme names, that are disallowed for use by the HTTP client implementation, for HTTP CONNECT tunneling.

• jdk.http.maxHeaderSize (default: 393216 or 384kB)
  The maximum header field section size that the client is prepared to accept. This is computed as the sum of the size of the uncompressed header name, plus the size of the uncompressed header value, plus an overhead of 32 bytes for each field section line. If a peer sends a field section that exceeds this size a ProtocolException will be raised. This applies to all versions of the protocol. A value of zero or a negative value means no limit.

The following system properties can be used to configure some aspects of the QUIC Protocol implementation used for HTTP/3:

• jdk.httpclient.quic.receiveBufferSize (default: operating system default)
  The QUIC UDP client socket receive buffer size in bytes. Values less than or equal to zero are ignored.

• jdk.httpclient.quic.sendBufferSize (default: operating system default)
  The QUIC UDP client socket send buffer size in bytes. Values less than or equal to zero are ignored.

• jdk.httpclient.quic.defaultMTU (default: 1200 bytes)
  The default Maximum Transmission Unit (MTU) size that will be used on quic connections. The default implementation of the HTTP/3 client does not implement Path MTU Detection, but will attempt to send 1-RTT packets up to the size defined by this property. Specifying a higher value may give better upload performance when the client and servers are located on the same machine, but is likely to result in irrecoverable packet loss if used over the network. Allowed values are in the range [1200, 65527]. If an out-of-range value is specified, the minimum default value will be used.

• jdk.httpclient.quic.maxBytesInFlight (default: 16777216 bytes or 16MB)
  This is the maximum number of unacknowledged bytes that the quic congestion controller allows to be in flight. When this amount is reached, no new data is sent until some of the packets in flight are acknowledged.
  Allowed values are in the range [2^14, 2^24] (or [16kB, 16MB]). If an out-of-range value is specified, it will be clamped to the closest value in range.

• jdk.httpclient.quic.maxInitialData (default: 15728640 bytes, or 15MB)
  The initial flow control limit for quic connections in bytes. Valid values are in the range [0, 2^60]. The initial limit is also used to initialize the receive window size. If less than 16kB, the window size will be set to 16kB.

• jdk.httpclient.quic.maxStreamInitialData (default: 6291456 bytes, or 6MB)
  The initial flow control limit for quic streams in bytes. Valid values are in the range [0, 2^60]. The initial limit is also used to initialize the receive window size. If less than 16kB, the window size will be set to 16kB.

• jdk.httpclient.quic.maxInitialTimeout (default: 30 seconds)
  This is the maximum time, in seconds, during which the client will wait for a response from the server, and continue retransmitting the first Quic INITIAL packet, before raising a java.net.ConnectException. The first INITIAL packet received from the target server will disarm this timeout.