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

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