- Enclosing class:
HttpRequest
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.
- Since:
- 11
-
Method Summary
Modifier and TypeMethodDescriptionbuild()
Builds and returns anHttpRequest
.copy()
Returns an exact duplicate copy of thisBuilder
based on current state.DELETE()
Sets the request method of this builder to DELETE.expectContinue
(boolean enable) Requests the server to acknowledge the request before sending the body.GET()
Sets the request method of this builder to GET.default HttpRequest.Builder
HEAD()
Sets the request method of this builder to HEAD.Adds the given name value pair to the set of headers for this request.Adds the given name value pairs to the set of headers for this request.method
(String method, HttpRequest.BodyPublisher bodyPublisher) Sets the request method and request body of this builder to the given values.POST
(HttpRequest.BodyPublisher bodyPublisher) Sets the request method of this builder to POST and sets its request body publisher to the given value.PUT
(HttpRequest.BodyPublisher bodyPublisher) Sets the request method of this builder to PUT and sets its request body publisher to the given value.Sets the given name value pair to the set of headers for this request.Sets a timeout for this request.Sets thisHttpRequest
's requestURI
.version
(HttpClient.Version version) Sets the preferredHttpClient.Version
for this request.
-
Method Details
-
uri
Sets thisHttpRequest
's requestURI
.- Parameters:
uri
- the request URI- Returns:
- this builder
- Throws:
IllegalArgumentException
- if theURI
scheme is not supported
-
expectContinue
Requests the server to acknowledge the request before sending the body. This is disabled by default. If enabled, the server is requested to send an error response or a100 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.- Parameters:
enable
-true
if Expect continue to be sent- Returns:
- this builder
-
version
Sets the preferredHttpClient.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 sendingHttpClient
.- Parameters:
version
- the HTTP protocol version requested- Returns:
- this builder
-
header
Adds the given name value pair to the set of headers for this request. The given value is added to the list of values for that name.- Implementation Note:
- An implementation may choose to restrict some header names
or values, as the HTTP Client may determine their value itself.
For example, "Content-Length", which will be determined by
the request Publisher. In such a case, an implementation of
HttpRequest.Builder
may choose to throw anIllegalArgumentException
if such a header is passed to the builder. - Parameters:
name
- the header namevalue
- the header value- Returns:
- this builder
- Throws:
IllegalArgumentException
- 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.
-
headers
Adds the given name value pairs to the set of headers for this request. The suppliedString
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.- Parameters:
headers
- the list of name value pairs- Returns:
- this builder
- Throws:
IllegalArgumentException
- 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.
-
timeout
Sets a timeout for this request. If the response is not received within the specified timeout then anHttpTimeoutException
is thrown fromHttpClient::send
orHttpClient::sendAsync
completes exceptionally with anHttpTimeoutException
. The effect of not setting a timeout is the same as setting an infinite Duration, i.e. block forever.- Parameters:
duration
- the timeout duration- Returns:
- this builder
- Throws:
IllegalArgumentException
- if the duration is non-positive
-
setHeader
Sets the given name value pair to the set of headers for this request. This overwrites any previously set values for name.- Parameters:
name
- the header namevalue
- the header value- Returns:
- this builder
- Throws:
IllegalArgumentException
- 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.
-
GET
HttpRequest.Builder GET()Sets the request method of this builder to GET. This is the default.- Returns:
- this builder
-
POST
Sets the request method of this builder to POST and sets its request body publisher to the given value.- Parameters:
bodyPublisher
- the body publisher- Returns:
- this builder
-
PUT
Sets the request method of this builder to PUT and sets its request body publisher to the given value.- Parameters:
bodyPublisher
- the body publisher- Returns:
- this builder
-
DELETE
HttpRequest.Builder DELETE()Sets the request method of this builder to DELETE.- Returns:
- this builder
-
HEAD
Sets the request method of this builder to HEAD.- Implementation Requirements:
- The default implementation is expected to have the same behaviour as:
return method("HEAD", BodyPublishers.noBody());
- Returns:
- this builder
- Since:
- 18
-
method
Sets the request method and request body of this builder to the given values.- API Note:
- The
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 theCONNECT
method. - Parameters:
method
- the method to usebodyPublisher
- the body publisher- Returns:
- this builder
- Throws:
IllegalArgumentException
- if the method name is not valid, see RFC 7230 section-3.1.1, or the method is restricted by the implementation.
-
build
HttpRequest build()Builds and returns anHttpRequest
.- Returns:
- a new
HttpRequest
- Throws:
IllegalStateException
- if a URI has not been set
-
copy
HttpRequest.Builder copy()Returns an exact duplicate copy of thisBuilder
based on current state. The new builder can then be modified independently of this builder.- Returns:
- an exact copy of this builder
-