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

# Interface HttpRequest.Builder

Enclosing class:
  `HttpRequest`

public static interface HttpRequest.Builder
A builder of HTTP requests.

Instances of `HttpRequest.Builder` are created by calling `HttpRequest.newBuilder()`, `HttpRequest.newBuilder(URI)`, or `HttpRequest.newBuilder(HttpRequest, BiPredicate)`.

The builder can be used to configure per-request state, such as: the request URI, the request method (default is GET unless explicitly set), specific request headers, etc. Each of the setter methods modifies the state of the builder and returns the same instance. The methods are not synchronized and should not be called from multiple threads without external synchronization. The `build` method returns a new `HttpRequest` each time it is invoked. Once built an `HttpRequest` is immutable, and can be sent multiple times.

Note, that not all request headers may be set by user code. Some are restricted for security reasons and others such as the headers relating to authentication, redirection and cookie management may be managed by specific APIs rather than through directly user set headers.

Since:
  11

- ## Method Summary

  Modifier and Type
  Method
  Description
  `HttpRequest`
  `build()`
  Builds and returns an `HttpRequest`.
  `HttpRequest.Builder`
  `copy()`
  Returns an exact duplicate copy of this `Builder` based on current state.
  `HttpRequest.Builder`
  `DELETE()`
  Sets the request method of this builder to DELETE.
  `HttpRequest.Builder`
  `expectContinue(boolean enable)`
  Requests the server to acknowledge the request before sending the body.
  `HttpRequest.Builder`
  `GET()`
  Sets the request method of this builder to GET.
  `default HttpRequest.Builder`
  `HEAD()`
  Sets the request method of this builder to HEAD.
  `HttpRequest.Builder`
  `header(String name, String value)`
  Adds the given name value pair to the set of headers for this request.
  `HttpRequest.Builder`
  `headers(String... headers)`
  Adds the given name value pairs to the set of headers for this request.
  `HttpRequest.Builder`
  `method(String method, HttpRequest.BodyPublisher bodyPublisher)`
  Sets the request method and request body of this builder to the given values.
  `HttpRequest.Builder`
  `POST(HttpRequest.BodyPublisher bodyPublisher)`
  Sets the request method of this builder to POST and sets its request body publisher to the given value.
  `HttpRequest.Builder`
  `PUT(HttpRequest.BodyPublisher bodyPublisher)`
  Sets the request method of this builder to PUT and sets its request body publisher to the given value.
  `HttpRequest.Builder`
  `setHeader(String name, String value)`
  Sets the given name value pair to the set of headers for this request.
  `default <T> HttpRequest.Builder`
  `setOption(HttpOption<T> option, T value)`
  Provides request configuration option hints modeled as key value pairs to help an `HttpClient` implementation decide how the request/response exchange should be established or carried out.
  `HttpRequest.Builder`
  `timeout(Duration duration)`
  Sets a timeout for this request.
  `HttpRequest.Builder`
  `uri(URI uri)`
  Sets this `HttpRequest`'s request `URI`.
  `HttpRequest.Builder`
  `version(HttpClient.Version version)`
  Sets the preferred `HttpClient.Version` for this request.

- ## Method Details

  - ### uri

    HttpRequest.Builder uri(URI uri)
    Sets this `HttpRequest`'s request `URI`.
    Parameters:
      `uri` - the request URI
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if the `URI` scheme is not supported

  - ### expectContinue

    HttpRequest.Builder expectContinue(boolean enable)
    Requests the server to acknowledge the request before sending the body. This is disabled by default. If enabled, the server is requested to send an error response or a `100 Continue` response before the client sends the request body. This means the request publisher for the request will not be invoked until this interim response is received.
    Parameters:
      `enable` - `true` if Expect continue to be sent
    Returns:
      this builder

  - ### version

    HttpRequest.Builder version(HttpClient.Version version)
    Sets the preferred `HttpClient.Version` for this request.

    The corresponding `HttpResponse` should be checked for the version that was actually used. If the version is not set in a request, then the version requested will be that of the sending `HttpClient`.

    Implementation Note:
      Constraints may also affect the selection of the actual protocol version.
    Parameters:
      `version` - the HTTP protocol version requested
    Returns:
      this builder

  - ### setOption

    default <T> HttpRequest.Builder setOption(HttpOption<T> option, T value)
    Provides request configuration option hints modeled as key value pairs to help an `HttpClient` implementation decide how the request/response exchange should be established or carried out.

    An `HttpClient` implementation may decide to ignore request configuration option hints, or fail the request, if provided with any option hints that it does not understand.

    If this method is invoked twice for the same request option, any value previously provided to this builder for the corresponding option is replaced by the new value. If `null` is supplied as a value, any value previously provided is discarded.

    Implementation Requirements:
      The default implementation of this method discards the provided option hint and does nothing.
    Implementation Note:
      The JDK built-in implementation of the `HttpClient` understands the request option `HttpOption.H3_DISCOVERY` hint.
    Parameters:
      `option` - the request configuration option
      `value` - the request configuration option value (can be null)
    Returns:
      this builder
    Since:
      26
    See Also:
      - `HttpRequest.getOption(HttpOption)`

  - ### header

    HttpRequest.Builder header(String name, String value)
    Adds the given name value pair to the set of headers for this request. The given value is added to the list of values for that name.
    Implementation Note:
      An implementation may choose to restrict some header names or values, as the HTTP Client may determine their value itself. For example, "Content-Length", which will be determined by the request Publisher. In such a case, an implementation of `HttpRequest.Builder` may choose to throw an `IllegalArgumentException` if such a header is passed to the builder.
    Parameters:
      `name` - the header name
      `value` - the header value
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if the header name or value is not valid, see RFC 7230 section-3.2, or the header name or value is restricted by the implementation.

  - ### headers

    HttpRequest.Builder headers(String... headers)
    Adds the given name value pairs to the set of headers for this request. The supplied `String` instances must alternate as header names and header values. To add several values to the same name then the same name must be supplied with each new value.
    Parameters:
      `headers` - the list of name value pairs
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if there are an odd number of parameters, or if a header name or value is not valid, see RFC 7230 section-3.2, or a header name or value is restricted by the implementation.

  - ### timeout

    HttpRequest.Builder timeout(Duration duration)
    Sets a timeout for this request. If the response is not received within the specified timeout then an `HttpTimeoutException` is thrown from `HttpClient::send` or `HttpClient::sendAsync` completes exceptionally with an `HttpTimeoutException`. The effect of not setting a timeout is the same as setting an infinite `Duration`, i.e., block forever.
    Implementation Requirements:
      A timeout applies to the duration measured from the instant the request execution starts to, at least, the instant an `HttpResponse` is constructed. The elapsed time includes obtaining a connection for transport and retrieving the response headers.
    Implementation Note:
      The JDK built-in implementation applies timeout over the duration measured from the instant the request execution starts to the instant the response body is consumed, if present. This is implemented by stopping the timer after the response body subscriber completion.
    Parameters:
      `duration` - the timeout duration
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if the duration is non-positive
    See Also:
      - Configuring timeout for connection establishment

  - ### setHeader

    HttpRequest.Builder setHeader(String name, String value)
    Sets the given name value pair to the set of headers for this request. This overwrites any previously set values for name.
    Parameters:
      `name` - the header name
      `value` - the header value
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if the header name or value is not valid, see RFC 7230 section-3.2, or the header name or value is restricted by the implementation.

  - ### GET

    HttpRequest.Builder GET()
    Sets the request method of this builder to GET. This is the default.
    Returns:
      this builder

  - ### POST

    HttpRequest.Builder POST(HttpRequest.BodyPublisher bodyPublisher)
    Sets the request method of this builder to POST and sets its request body publisher to the given value.
    Parameters:
      `bodyPublisher` - the body publisher
    Returns:
      this builder

  - ### PUT

    HttpRequest.Builder PUT(HttpRequest.BodyPublisher bodyPublisher)
    Sets the request method of this builder to PUT and sets its request body publisher to the given value.
    Parameters:
      `bodyPublisher` - the body publisher
    Returns:
      this builder

  - ### DELETE

    HttpRequest.Builder DELETE()
    Sets the request method of this builder to DELETE.
    Returns:
      this builder

  - ### HEAD

    default HttpRequest.Builder HEAD()
    Sets the request method of this builder to HEAD.
    Implementation Requirements:
      The default implementation is expected to have the same behaviour as: `return method("HEAD", BodyPublishers.noBody());`
    Returns:
      this builder
    Since:
      18

  - ### method

    HttpRequest.Builder method(String method, HttpRequest.BodyPublisher bodyPublisher)
    Sets the request method and request body of this builder to the given values.
    API Note:
      The `noBody` request body publisher can be used where no request body is required or appropriate. Whether a method is restricted, or not, is implementation specific. For example, some implementations may choose to restrict the `CONNECT` method.
    Parameters:
      `method` - the method to use
      `bodyPublisher` - the body publisher
    Returns:
      this builder
    Throws:
      `IllegalArgumentException` - if the method name is not valid, see RFC 7230 section-3.1.1, or the method is restricted by the implementation.

  - ### build

    HttpRequest build()
    Builds and returns an `HttpRequest`.
    Implementation Requirements:
      This method returns a new `HttpRequest` each time it is invoked. Once built, the `HttpRequest` is immutable and can be sent multiple times.
    Returns:
      a new `HttpRequest`
    Throws:
      `IllegalStateException` - if a URI has not been set

  - ### copy

    HttpRequest.Builder copy()
    Returns an exact duplicate copy of this `Builder` based on current state. The new builder can then be modified independently of this builder.
    Returns:
      an exact copy of this builder