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
Modifier and TypeClassDescriptionstatic interface
ABodyPublisher
converts high-level Java objects into a flow of byte buffers suitable for sending as a request body.static class
Implementations ofBodyPublisher
that implement various useful publishers, such as publishing the request body from a String, or from a file.static interface
A builder of HTTP requests. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract Optional<HttpRequest.BodyPublisher>
Returns anOptional
containing theHttpRequest.BodyPublisher
set on this request.final boolean
Tests this HTTP request instance for equality with the given object.abstract boolean
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
Creates anHttpRequest
builder.static HttpRequest.Builder
newBuilder
(HttpRequest request, BiPredicate<String, String> filter) Creates aBuilder
whose initial state is copied from an existingHttpRequest
.static HttpRequest.Builder
newBuilder
(URI uri) Creates anHttpRequest
builder with the given URI.timeout()
Returns anOptional
containing this request's timeout duration.abstract URI
uri()
Returns this request'sURI
.abstract Optional<HttpClient.Version>
version()
Returns anOptional
containing the HTTP protocol version that will be requested for thisHttpRequest
.
-
Constructor Details
-
HttpRequest
protected HttpRequest()Creates an HttpRequest.
-
-
Method Details
-
newBuilder
Creates anHttpRequest
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 aBuilder
whose initial state is copied from an existingHttpRequest
.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 thefilter
will be present in theBuilder
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"))
- Retain all headers:
- Parameters:
request
- the original requestfilter
- 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
Creates anHttpRequest
builder.- Returns:
- a new request builder
-
bodyPublisher
Returns anOptional
containing theHttpRequest.BodyPublisher
set on this request. If noBodyPublisher
was set in the requests's builder, then theOptional
is empty.- Returns:
- an
Optional
containing this request'sBodyPublisher
-
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
Returns anOptional
containing this request's timeout duration. If the timeout duration was not set in the request's builder, then theOptional
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
Returns this request'sURI
.- Returns:
- this request's URI
-
version
Returns anOptional
containing the HTTP protocol version that will be requested for thisHttpRequest
. If the version was not set in the request's builder, then theOptional
is empty. In that case, the version requested will be that of the sendingHttpClient
. The correspondingHttpResponse
should be queried to determine the version that was actually used.- Returns:
- HTTP protocol version
-
headers
The (user-accessible) request headers that this request was (or will be) sent with.- Returns:
- this request's HttpHeaders
-
equals
Tests this HTTP request instance for equality with the given object.If the given object is not an
HttpRequest
then this method returnsfalse
. 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. -
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.
-