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.
    <T> Optional<T>
    getOption(HttpOption<T> option)
    Returns the value configured on this request for the given option, if any.
    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 Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
    Modifier and Type
    Method
    Description
    protected Object
    clone()
    Creates and returns a copy of this object.
    protected void
    finalize()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Finalization is deprecated and subject to removal in a future release.
    final Class<?>
    getClass()
    Returns the runtime class of this Object.
    final void
    notify()
    Wakes up a single thread that is waiting on this object's monitor.
    final void
    notifyAll()
    Wakes up all threads that are waiting on this object's monitor.
    String
    toString()
    Returns a string representation of the object.
    final void
    wait()
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
    final void
    wait(long timeoutMillis)
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
    final void
    wait(long timeoutMillis, int nanos)
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

  • Constructor Details

    • HttpRequest

      protected HttpRequest()
      Creates an HttpRequest.

  • Method Details

    • getOption

      public <T> Optional<T> getOption(HttpOption<T> option)
      Returns the value configured on this request for the given option, if any.
      Implementation Requirements:
      The default implementation of this method returns Optional.empty() if option is non-null, otherwise throws NullPointerException.
      Type Parameters:
      T - the type of the option
      Parameters:
      option - a request configuration option
      Returns:
      the value configured on this request for the given option, if any
      Since:
      26
      See Also:

    • 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:

    • 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: