APIdia Launch Partner
Top Description Inners Fields Methods
java.net.http

public sealed Interface HttpOption<T>

permits HttpRequestOptionImpl<T>
Known Direct Implementers
java.net.http.HttpRequestOptionImpl
Type Parameters
<T>
The type of the option value
Imports
java.net.ProxySelector, .URI, java.net.http.HttpClient.Version, .HttpRequest.Builder
This interface is used to provide additional request configuration option hints on how an HTTP request/response exchange should be carried out by the HttpClient implementation. Request configuration option hints can be provided to an HttpRequest with the HttpRequest.Builder setOption method.

Concrete instances of this class and its subclasses are immutable.

API Note

In this version, the HttpOption interface is sealed and only allows the H3_DISCOVERY option. However, it could be extended in the future to support additional options.

The H3_DISCOVERY option can be used to help the HttpClient decide how to select or establish an HTTP/3 connection through which to carry out an HTTP/3 request/response exchange.

Since
26

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
HttpOption.Http3DiscoveryMode

This enumeration can be used to help the HttpClient decide how an HTTP/3 exchange should be established, and can be provided as the value of the HttpOption#H3_DISCOVERY option to Builder.setOption.

Field Summary

Modifier and TypeField and Description
public static final HttpOption<HttpOption.Http3DiscoveryMode>
H3_DISCOVERY

An option that can be used to configure how the HttpClient will select or establish an HTTP/3 connection through which to carry out the request.

Method Summary

Modifier and TypeMethod and Description
public String

Returns:

the option name
name()

Returns the option name.

public Class<T>

Returns:

the type of the value associated with the option
type()

Returns the type of the value associated with the option.

Field Detail

H3_DISCOVERYback to summary
public static final HttpOption<HttpOption.Http3DiscoveryMode> H3_DISCOVERY

An option that can be used to configure how the HttpClient will select or establish an HTTP/3 connection through which to carry out the request. If Version#HTTP_3 is not selected either as the request preferred version or the HttpClient preferred version setting this option on the request has no effect.

The name of this option is "H3_DISCOVERY".

Implementation Note

The JDK built-in implementation of the HttpClient understands the request option H3_DISCOVERY hint.
If no H3_DISCOVERY hint is provided, and the HTTP/3 version is selected, either as request preferred version or client preferred version, the JDK built-in implementation will establish the exchange as per Http3DiscoveryMode#ANY.

In case of redirect, the H3_DISCOVERY option, if present, is always transferred to the new request.

In this implementation, HTTP/3 through proxies is not supported. Unless Http3DiscoveryMode#HTTP_3_URI_ONLY is specified, if a proxy is selected for the request URI, the protocol version is downgraded to HTTP/2 or HTTP/1.1 and the H3_DISCOVERY option is ignored. If, on the other hand, Http3DiscoveryMode#HTTP_3_URI_ONLY is specified, the request will fail.

See Also
Http3DiscoveryMode, Builder#setOption(HttpOption, Object)

Method Detail

nameback to summary
public String name()

Returns the option name.

Implementation Specification

Different options must have different names.

Returns:String

the option name

typeback to summary
public Class<T> type()

Returns the type of the value associated with the option.

API Note

Different options may have the same type.

Returns:Class<T>

the type of the value associated with the option

java.net.http back to summary

public final Enum HttpOption.Http3DiscoveryMode

extends Enum<HttpOption.Http3DiscoveryMode>
Class Inheritance
This enumeration can be used to help the HttpClient decide how an HTTP/3 exchange should be established, and can be provided as the value of the HttpOption#H3_DISCOVERY option to Builder.setOption.

Note that if neither the request preferred version nor the client preferred version is HTTP/3, no HTTP/3 exchange will be established and the Http3DiscoveryMode is ignored.

Since
26

Field Summary

Modifier and TypeField and Description
public static final HttpOption.Http3DiscoveryMode
ALT_SVC

This instructs the HttpClient to only use the HTTP Alternative Services to find or establish an HTTP/3 connection with the origin server.

public static final HttpOption.Http3DiscoveryMode
ANY

This instructs the HttpClient to use its own implementation specific algorithm to find or establish a connection for the exchange.

public static final HttpOption.Http3DiscoveryMode
HTTP_3_URI_ONLY

This instructs the HttpClient to only attempt an HTTP/3 connection with the origin server.

Constructor Summary

AccessConstructor and Description
private
Http3DiscoveryMode()

Method Summary

Modifier and TypeMethod and Description
public static HttpOption.Http3DiscoveryMode
valueOf(String name)

public static HttpOption.Http3DiscoveryMode[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

ALT_SVCback to summary
public static final HttpOption.Http3DiscoveryMode ALT_SVC

This instructs the HttpClient to only use the HTTP Alternative Services to find or establish an HTTP/3 connection with the origin server. The exchange may then be carried out with any of the three HTTP protocol versions, depending on whether an Alternate Service record for HTTP/3 could be found, and which HTTP version was negotiated with the origin server, if no such record could be found.

In this mode, requests sent to the origin server will be sent through HTTP/1.1 or HTTP/2 until a h3 HTTP Alternative Services endpoint for that server is advertised to the client. Usually, an alternate service is advertised by a server when responding to a request, so that subsequent requests can make use of that alternative service.

ANYback to summary
public static final HttpOption.Http3DiscoveryMode ANY

This instructs the HttpClient to use its own implementation specific algorithm to find or establish a connection for the exchange. Typically, if no connection was previously established with the origin server defined by the request URI, the HttpClient implementation may attempt to establish both an HTTP/3 connection over QUIC and an HTTP connection over TLS/TCP at the authority present in the request URI, and use the first that succeeds. The exchange may then be carried out with any of the three HTTP protocol versions, depending on which method succeeded first.

Implementation Note

If the request preferred version is HTTP/3, the HttpClient may give priority to HTTP/3 by attempting to establish an HTTP/3 connection, before attempting a TLS connection over TCP.

When attempting an HTTP/3 connection in this mode, the HttpClient may use any HTTP Alternative Services information it may have previously obtained from the origin server. If no such information is available, a direct HTTP/3 connection at the authority (host, port) present in the request URI will be attempted.

HTTP_3_URI_ONLYback to summary
public static final HttpOption.Http3DiscoveryMode HTTP_3_URI_ONLY

This instructs the HttpClient to only attempt an HTTP/3 connection with the origin server. The connection will only succeed if the origin server is listening for incoming HTTP/3 connections over QUIC at the same authority (host, port) as defined in the request URI. In this mode, HTTP Alternative Services are not used.

Constructor Detail

Http3DiscoveryModeback to summary
private Http3DiscoveryMode()

Method Detail

valueOfback to summary
public static HttpOption.Http3DiscoveryMode valueOf(String name)
valuesback to summary
public static HttpOption.Http3DiscoveryMode[] values()