HttpRequest
public static interface HttpRequest.Builder
Instances of HttpRequest.Builder
are created by calling HttpRequest.newBuilder()
, HttpRequest.newBuilder(URI)
, or HttpRequest.newBuilder(HttpRequest, BiPredicate)
.
The builder can be used to configure per-request state, such as: the request URI, the request method (default is GET unless explicitly set), specific request headers, etc. Each of the setter methods modifies the state of the builder and returns the same instance. The methods are not synchronized and should not be called from multiple threads without external synchronization. The build
method returns a new HttpRequest
each time it is invoked. Once built an
HttpRequest
is immutable, and can be sent multiple times.
Note, that not all request headers may be set by user code. Some are restricted for security reasons and others such as the headers relating to authentication, redirection and cookie management may be managed by specific APIs rather than through directly user set headers.
Modifier and Type | Method | Description |
---|---|---|
HttpRequest |
build() |
Builds and returns an HttpRequest . |
HttpRequest.Builder |
copy() |
Returns an exact duplicate copy of this Builder based on current state. |
HttpRequest.Builder |
DELETE() |
Sets the request method of this builder to DELETE. |
HttpRequest.Builder |
expectContinue |
Requests the server to acknowledge the request before sending the body. |
HttpRequest.Builder |
GET() |
Sets the request method of this builder to GET. |
default HttpRequest.Builder |
HEAD() |
Sets the request method of this builder to HEAD. |
HttpRequest.Builder |
header |
Adds the given name value pair to the set of headers for this request. |
HttpRequest.Builder |
headers |
Adds the given name value pairs to the set of headers for this request. |
HttpRequest.Builder |
method |
Sets the request method and request body of this builder to the given values. |
HttpRequest.Builder |
POST |
Sets the request method of this builder to POST and sets its request body publisher to the given value. |
HttpRequest.Builder |
PUT |
Sets the request method of this builder to PUT and sets its request body publisher to the given value. |
HttpRequest.Builder |
setHeader |
Sets the given name value pair to the set of headers for this request. |
HttpRequest.Builder |
timeout |
Sets a timeout for this request. |
HttpRequest.Builder |
uri |
Sets this HttpRequest 's request URI . |
HttpRequest.Builder |
version |
Sets the preferred HttpClient.Version for this request. |
HttpRequest.Builder uri(URI uri)
HttpRequest
's request URI
.uri
- the request URIIllegalArgumentException
- if the URI
scheme is not supportedHttpRequest.Builder expectContinue(boolean enable)
100 Continue
response before the client sends the request body. This means the request publisher for the request will not be invoked until this interim response is received.enable
- true
if Expect continue to be sentHttpRequest.Builder version(HttpClient.Version version)
HttpClient.Version
for this request. The corresponding HttpResponse
should be checked for the version that was actually used. If the version is not set in a request, then the version requested will be that of the sending HttpClient
.
version
- the HTTP protocol version requestedHttpRequest.Builder header(String name, String value)
HttpRequest.Builder
may choose to throw an IllegalArgumentException
if such a header is passed to the builder.name
- the header namevalue
- the header valueIllegalArgumentException
- if the header name or value is not valid, see RFC 7230 section-3.2, or the header name or value is restricted by the implementation.HttpRequest.Builder headers(String... headers)
String
instances must alternate as header names and header values. To add several values to the same name then the same name must be supplied with each new value.headers
- the list of name value pairsIllegalArgumentException
- if there are an odd number of parameters, or if a header name or value is not valid, see RFC 7230 section-3.2, or a header name or value is restricted by the implementation.HttpRequest.Builder timeout(Duration duration)
HttpTimeoutException
is thrown from HttpClient::send
or HttpClient::sendAsync
completes exceptionally with an HttpTimeoutException
. The effect of not setting a timeout is the same as setting an infinite Duration, i.e. block forever.duration
- the timeout durationIllegalArgumentException
- if the duration is non-positiveHttpRequest.Builder setHeader(String name, String value)
name
- the header namevalue
- the header valueIllegalArgumentException
- if the header name or value is not valid, see RFC 7230 section-3.2, or the header name or value is restricted by the implementation.HttpRequest.Builder GET()
HttpRequest.Builder POST(HttpRequest.BodyPublisher bodyPublisher)
bodyPublisher
- the body publisherHttpRequest.Builder PUT(HttpRequest.BodyPublisher bodyPublisher)
bodyPublisher
- the body publisherHttpRequest.Builder DELETE()
default HttpRequest.Builder HEAD()
return method("HEAD", BodyPublishers.noBody());
HttpRequest.Builder method(String method, HttpRequest.BodyPublisher bodyPublisher)
noBody
request body publisher can be used where no request body is required or appropriate. Whether a method is restricted, or not, is implementation specific. For example, some implementations may choose to restrict the CONNECT
method.method
- the method to usebodyPublisher
- the body publisherIllegalArgumentException
- if the method name is not valid, see RFC 7230 section-3.1.1, or the method is restricted by the implementation.HttpRequest build()
HttpRequest
.HttpRequest
each time it is invoked. Once built, the HttpRequest
is immutable and can be sent multiple times.HttpRequest
IllegalStateException
- if a URI has not been setHttpRequest.Builder copy()
Builder
based on current state. The new builder can then be modified independently of this builder.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.net.http/java/net/http/HttpRequest.Builder.html