Module java.net.http
Package java.net.http

# Class HttpRequest

java.lang.Object
java.net.http.HttpRequest

public abstract class HttpRequest extends Object
An HTTP request.

An `HttpRequest` instance is built through an `HttpRequest` builder. An `HttpRequest` builder is obtained from one of the `newBuilder` methods. A request's `URI`, headers, and body can be set. Request bodies are provided through a `BodyPublisher` supplied to one of the `POST`, `PUT` or `method` methods. Once all required parameters have been set in the builder, `build` will return the `HttpRequest`. Builders can be copied and modified many times in order to build multiple related requests that differ in some parameters.

The following is an example of a GET request that prints the response body as a String:

    HttpClient client = HttpClient.newHttpClient();

    HttpRequest request = HttpRequest.newBuilder()
          .uri(URI.create("http://foo.com/"))
          .build();

    client.sendAsync(request, BodyHandlers.ofString())
          .thenApply(HttpResponse::body)
          .thenAccept(System.out::println)
          .join();

The class `BodyPublishers` provides implementations of many common publishers. Alternatively, a custom `BodyPublisher` implementation can be used.

Since:
  11

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `HttpRequest.BodyPublisher`
  A `BodyPublisher` converts high-level Java objects into a flow of byte buffers suitable for sending as a request body.
  `static class`
  `HttpRequest.BodyPublishers`
  Implementations of `BodyPublisher` that implement various useful publishers, such as publishing the request body from a String, or from a file.
  `static interface`
  `HttpRequest.Builder`
  A builder of HTTP requests.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `HttpRequest()`
  Creates an HttpRequest.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract Optional<HttpRequest.BodyPublisher>`
  `bodyPublisher()`
  Returns an `Optional` containing the `HttpRequest.BodyPublisher` set on this request.
  `final boolean`
  `equals(Object obj)`
  Tests this HTTP request instance for equality with the given object.
  `abstract boolean`
  `expectContinue()`
  Returns this request's expect continue setting.
  `final int`
  `hashCode()`
  Computes a hash code for this HTTP request instance.
  `abstract HttpHeaders`
  `headers()`
  The (user-accessible) request headers that this request was (or will be) sent with.
  `abstract String`
  `method()`
  Returns the request method for this request.
  `static HttpRequest.Builder`
  `newBuilder()`
  Creates an `HttpRequest` builder.
  `static HttpRequest.Builder`
  `newBuilder(HttpRequest request, BiPredicate<String,String> filter)`
  Creates a `Builder` whose initial state is copied from an existing `HttpRequest`.
  `static HttpRequest.Builder`
  `newBuilder(URI uri)`
  Creates an `HttpRequest` builder with the given URI.
  `abstract Optional<Duration>`
  `timeout()`
  Returns an `Optional` containing this request's timeout duration.
  `abstract URI`
  `uri()`
  Returns this request's `URI`.
  `abstract Optional<HttpClient.Version>`
  `version()`
  Returns an `Optional` containing the HTTP protocol version that will be requested for this `HttpRequest`.

  ### Methods declared in class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### HttpRequest

    protected HttpRequest()
    Creates an HttpRequest.

- ## Method Details

  - ### newBuilder

    public static HttpRequest.Builder newBuilder(URI uri)
    Creates an `HttpRequest` builder with the given URI.
    Parameters:
      `uri` - the request URI
    Returns:
      a new request builder
    Throws:
      `IllegalArgumentException` - if the URI scheme is not supported.

  - ### newBuilder

    public static HttpRequest.Builder newBuilder(HttpRequest request, BiPredicate<String,String> filter)
    Creates a `Builder` whose initial state is copied from an existing `HttpRequest`.

    This builder can be used to build an `HttpRequest`, equivalent to the original, while allowing amendment of the request state prior to construction - for example, adding additional headers.

    The `filter` is applied to each header name value pair as they are copied from the given request. When completed, only headers that satisfy the condition as laid out by the `filter` will be present in the `Builder` returned from this method.

    API Note:
      The following scenarios demonstrate typical use-cases of the filter. Given an `HttpRequest` request:
      - Retain all headers:

            HttpRequest.newBuilder(request, (n, v) -> true)

      - Remove all headers:

            HttpRequest.newBuilder(request, (n, v) -> false)

      - Remove a particular header (e.g. Foo-Bar):

            HttpRequest.newBuilder(request, (name, value) -> !name.equalsIgnoreCase("Foo-Bar"))

    Parameters:
      `request` - the original request
      `filter` - a header filter
    Returns:
      a new request builder
    Throws:
      `IllegalArgumentException` - if a new builder cannot be seeded from the given request (for instance, if the request contains illegal parameters)
    Since:
      16

  - ### newBuilder

    public static HttpRequest.Builder newBuilder()
    Creates an `HttpRequest` builder.
    Returns:
      a new request builder

  - ### bodyPublisher

    public abstract Optional<HttpRequest.BodyPublisher> bodyPublisher()
    Returns an `Optional` containing the `HttpRequest.BodyPublisher` set on this request. If no `BodyPublisher` was set in the requests's builder, then the `Optional` is empty.
    Returns:
      an `Optional` containing this request's `BodyPublisher`

  - ### method

    public abstract String method()
    Returns the request method for this request. If not set explicitly, the default method for any request is "GET".
    Returns:
      this request's method

  - ### timeout

    public abstract Optional<Duration> timeout()
    Returns an `Optional` containing this request's timeout duration. If the timeout duration was not set in the request's builder, then the `Optional` is empty.
    Returns:
      an `Optional` containing this request's timeout duration

  - ### expectContinue

    public abstract boolean expectContinue()
    Returns this request's expect continue setting.
    Returns:
      this request's expect continue setting

  - ### uri

    public abstract URI uri()
    Returns this request's `URI`.
    Returns:
      this request's URI

  - ### version

    public abstract Optional<HttpClient.Version> version()
    Returns an `Optional` containing the HTTP protocol version that will be requested for this `HttpRequest`. If the version was not set in the request's builder, then the `Optional` is empty. In that case, the version requested will be that of the sending `HttpClient`. The corresponding `HttpResponse` should be queried to determine the version that was actually used.
    Returns:
      HTTP protocol version

  - ### headers

    public abstract HttpHeaders headers()
    The (user-accessible) request headers that this request was (or will be) sent with.
    Returns:
      this request's HttpHeaders

  - ### equals

    public final boolean equals(Object obj)
    Tests this HTTP request instance for equality with the given object.

    If the given object is not an `HttpRequest` then this method returns `false`. Two HTTP requests are equal if their URI, method, and headers fields are all equal.

    This method satisfies the general contract of the `Object.equals` method.

    Overrides:
      `equals` in class `Object`
    Parameters:
      `obj` - the object to which this object is to be compared
    Returns:
      `true` if, and only if, the given object is an `HttpRequest` that is equal to this HTTP request
    See Also:
      - `Object.hashCode()`
      - `HashMap`

  - ### hashCode

    public final int hashCode()
    Computes a hash code for this HTTP request instance.

    The hash code is based upon the HTTP request's URI, method, and header components, and satisfies the general contract of the `Object.hashCode` method.

    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hash-code value for this HTTP request
    See Also:
      - `Object.equals(java.lang.Object)`
      - `System.identityHashCode(java.lang.Object)`