HttpOption (Java SE 26 & JDK 26)
Description: declaration: module: java.net.http, package: java.net.http, interface: HttpOption
Keywords: java.net.http.HttpOption interface

# Interface HttpOption<T>

Type Parameters:
  `T` - The type of the option value

public sealed interface HttpOption<T>
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 Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `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 `H3_DISCOVERY` option to `Builder.setOption`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `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 Type
  Method
  Description
  `String`
  `name()`
  Returns the option name.
  `Class<T>`
  `type()`
  Returns the type of the value associated with the option.

- ## Field Details

  - ### H3_DISCOVERY

    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 `HttpClient.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 `HttpOption.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 `HttpOption.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, `HttpOption.Http3DiscoveryMode.HTTP_3_URI_ONLY` is specified, the request will fail.

    See Also:
      - `HttpOption.Http3DiscoveryMode`
      - `HttpRequest.Builder.setOption(HttpOption, Object)`

- ## Method Details

  - ### name

    String name()
    Returns the option name.
    Implementation Requirements:
      Different options must have different names.
    Returns:
      the option name

  - ### type

    Class<T> type()
    Returns the type of the value associated with the option.
    API Note:
      Different options may have the same type.
    Returns:
      the type of the value associated with the option