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.
    `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.
    `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​(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 Detail

    - #### HttpRequest

          protected HttpRequest()

      Creates an HttpRequest.

  - ### Method Detail

    - #### 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()

      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)`