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
`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
`protected` `HttpRequest()` Creates an HttpRequest.

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`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)`