T
- the type of response bodypublic interface HttpRequest<T>
Instances are created by an WebClient
instance, via one of the methods corresponding to the specific
HTTP methods such as WebClient.get(java.lang.String)
, etc...
The request shall be configured prior sending, the request is immutable and when a mutator method is called, a new request is returned allowing to expose the request in a public API and apply further customization.
After the request has been configured, the methods
send(Handler)
sendStream(ReadStream, Handler)
sendJson(Object, Handler)
()}sendForm(MultiMap, Handler)
sendXXX
methods perform the actual request, they can be called multiple times to perform the same HTTP
request at different points in time.
The handler is called back with
HttpResponse
instance when the HTTP response has been received
Most of the time, this client will buffer the HTTP response fully unless a specific BodyCodec
is used
such as BodyCodec.create(Handler)
.
Modifier and Type | Method and Description |
---|---|
HttpRequest<T> |
addQueryParam(String paramName,
String paramValue)
Add a query parameter to the request.
|
<U> HttpRequest<U> |
as(BodyCodec<U> responseCodec)
Configure the request to decode the response with the
responseCodec . |
HttpRequest<T> |
authentication(Credentials credentials)
Configure the request to perform HTTP Authentication.
|
default HttpRequest<T> |
basicAuthentication(Buffer id,
Buffer password)
Configure the request to perform basic access authentication.
|
default HttpRequest<T> |
basicAuthentication(String id,
String password)
Configure the request to perform basic access authentication.
|
default HttpRequest<T> |
bearerTokenAuthentication(String bearerToken)
Configure the request to perform bearer token authentication.
|
BodyCodec<T> |
bodyCodec() |
HttpRequest<T> |
copy()
Copy this request
|
default HttpRequest<T> |
expect(java.util.function.Function<HttpResponse<Void>,ResponsePredicateResult> predicate)
Add an expectation that the response is valid according to the provided
predicate . |
HttpRequest<T> |
expect(ResponsePredicate predicate)
Add an expectation that the response is valid according to the provided
predicate . |
List<ResponsePredicate> |
expectations() |
boolean |
followRedirects() |
HttpRequest<T> |
followRedirects(boolean value)
Set whether to follow request redirections
|
MultiMap |
headers() |
String |
host() |
HttpRequest<T> |
host(String value)
Configure the request to use a new host
value . |
HttpMethod |
method() |
HttpRequest<T> |
method(HttpMethod value)
Configure the request to use a new method
value . |
boolean |
multipartMixed() |
HttpRequest<T> |
multipartMixed(boolean allow)
Allow or disallow multipart mixed encoding when sending
MultipartForm having files sharing the same
file name. |
int |
port() |
HttpRequest<T> |
port(int value)
Configure the request to use a new port
value . |
ProxyOptions |
proxy() |
HttpRequest<T> |
proxy(ProxyOptions proxyOptions)
Configure the request to set a proxy for this request.
|
HttpRequest<T> |
putHeader(String name,
Iterable<String> value)
Configure the request to set a new HTTP header with multiple values.
|
HttpRequest<T> |
putHeader(String name,
String value)
Configure the request to set a new HTTP header.
|
HttpRequest<T> |
putHeaders(MultiMap headers)
Configure the request to add multiple HTTP headers .
|
MultiMap |
queryParams()
Return the current query parameters.
|
default Future<HttpResponse<T>> |
send() |
void |
send(Handler<AsyncResult<HttpResponse<T>>> handler)
Send a request, the
handler will receive the response as an HttpResponse . |
default Future<HttpResponse<T>> |
sendBuffer(Buffer body) |
void |
sendBuffer(Buffer body,
Handler<AsyncResult<HttpResponse<T>>> handler)
Like
send(Handler) but with an HTTP request body buffer. |
default Future<HttpResponse<T>> |
sendForm(MultiMap body) |
void |
sendForm(MultiMap body,
Handler<AsyncResult<HttpResponse<T>>> handler)
Like
send(Handler) but with an HTTP request body multimap encoded as form and the content type
set to application/x-www-form-urlencoded . |
default Future<HttpResponse<T>> |
sendForm(MultiMap body,
String charset) |
void |
sendForm(MultiMap body,
String charset,
Handler<AsyncResult<HttpResponse<T>>> handler)
Like
send(Handler) but with an HTTP request body multimap encoded as form and the content type
set to application/x-www-form-urlencoded . |
default Future<HttpResponse<T>> |
sendJson(Object body) |
void |
sendJson(Object body,
Handler<AsyncResult<HttpResponse<T>>> handler)
Like
send(Handler) but with an HTTP request body object encoded as json and the content type
set to application/json . |
default Future<HttpResponse<T>> |
sendJsonObject(JsonObject body) |
void |
sendJsonObject(JsonObject body,
Handler<AsyncResult<HttpResponse<T>>> handler)
Like
send(Handler) but with an HTTP request body object encoded as json and the content type
set to application/json . |
default Future<HttpResponse<T>> |
sendMultipartForm(MultipartForm body) |
void |
sendMultipartForm(MultipartForm body,
Handler<AsyncResult<HttpResponse<T>>> handler)
Like
send(Handler) but with an HTTP request body multimap encoded as form and the content type
set to multipart/form-data . |
default Future<HttpResponse<T>> |
sendStream(ReadStream<Buffer> body) |
void |
sendStream(ReadStream<Buffer> body,
Handler<AsyncResult<HttpResponse<T>>> handler)
Like
send(Handler) but with an HTTP request body stream. |
HttpRequest<T> |
setQueryParam(String paramName,
String paramValue)
Set a query parameter to the request.
|
HttpRequest<T> |
setTemplateParam(String paramName,
List<String> paramValue)
Set a request URI template list parameter to the request, expanded when the request URI is a
UriTemplate . |
HttpRequest<T> |
setTemplateParam(String paramName,
Map<String,String> paramValue)
Set a request URI template map parameter to the request, expanded when the request URI is a
UriTemplate . |
HttpRequest<T> |
setTemplateParam(String paramName,
String paramValue)
Set a request URI template string parameter to the request, expanded when the request URI is a
UriTemplate . |
Boolean |
ssl() |
HttpRequest<T> |
ssl(Boolean value)
Configure the request whether to use SSL.
|
Variables |
templateParams()
Return the current request URI template parameters.
|
long |
timeout() |
HttpRequest<T> |
timeout(long value)
Configures the amount of time in milliseconds after which if the request does not return any data within the timeout
period an
TimeoutException fails the request. |
String |
traceOperation() |
HttpRequest<T> |
traceOperation(String traceOperation)
Trace operation name override.
|
String |
uri() |
HttpRequest<T> |
uri(String value)
Configure the request to use a new request URI
value . |
String |
virtualHost() |
HttpRequest<T> |
virtualHost(String value)
Configure the request to use a virtual host
value . |
HttpRequest<T> method(HttpMethod value)
value
.HttpMethod method()
HttpRequest<T> port(int value)
value
.
This overrides the port set by absolute URI requests
int port()
0
when none is set for absolute URI templates<U> HttpRequest<U> as(BodyCodec<U> responseCodec)
responseCodec
.responseCodec
- the response codecHttpRequest<T> host(String value)
value
.
This overrides the host set by absolute URI requests
String host()
null
when none is set for absolute URI templatesHttpRequest<T> virtualHost(String value)
value
.
Usually the header host (:authority pseudo header for HTTP/2) is set from the request host value
since this host value resolves to the server IP address.
Sometimes you need to set a host header for an address that does not resolve to the server IP address.
The virtual host value overrides the value of the actual host header (:authority pseudo header
for HTTP/2).
The virtual host is also be used for SNI.String virtualHost()
null
HttpRequest<T> uri(String value)
value
.
This overrides the port set by absolute URI requests
When the uri has query parameters, they are set in the queryParams()
, overwriting
any parameters previously set
String uri()
null
when none is set for absolute URI templatesHttpRequest<T> putHeaders(MultiMap headers)
headers
- The HTTP headersHttpRequest<T> putHeader(String name, String value)
name
- the header namevalue
- the header valueHttpRequest<T> putHeader(String name, Iterable<String> value)
name
- the header namevalue
- the header valueMultiMap headers()
HttpRequest<T> authentication(Credentials credentials)
Performs a generic authentication using the credentials provided by the user. For the sake of validation safety
it is recommended that Credentials.applyHttpChallenge(String)
is called to ensure that the credentials
are applicable to the HTTP Challenged received on a previous request that returned a 401 response code.
credentials
- the credentials to use.default HttpRequest<T> basicAuthentication(String id, String password)
In basic HTTP authentication, a request contains a header field of the form 'Authorization: Basic <credentials>', where credentials is the base64 encoding of id and password joined by a colon.
In practical terms the arguments are converted to aUsernamePasswordCredentials
object.id
- the idpassword
- the passworddefault HttpRequest<T> basicAuthentication(Buffer id, Buffer password)
In basic HTTP authentication, a request contains a header field of the form 'Authorization: Basic <credentials>', where credentials is the base64 encoding of id and password joined by a colon.
In practical terms the arguments are converted to aUsernamePasswordCredentials
object.id
- the idpassword
- the passworddefault HttpRequest<T> bearerTokenAuthentication(String bearerToken)
In OAuth 2.0, a request contains a header field of the form 'Authorization: Bearer <bearerToken>', where bearerToken is the bearer token issued by an authorization server to access protected resources.
In practical terms the arguments are converted to aTokenCredentials
object.bearerToken
- the bearer tokenHttpRequest<T> ssl(Boolean value)
This overrides the SSL value set by absolute URI requests
Boolean ssl()
null
when none is set for absolute URI templatesHttpRequest<T> timeout(long value)
TimeoutException
fails the request.
Setting zero or a negative value
disables the timeout.
value
- The quantity of time in milliseconds.long timeout()
HttpRequest<T> addQueryParam(String paramName, String paramValue)
paramName
- the param nameparamValue
- the param valueHttpRequest<T> setQueryParam(String paramName, String paramValue)
paramName
- the param nameparamValue
- the param valueHttpRequest<T> setTemplateParam(String paramName, String paramValue)
UriTemplate
.paramName
- the param nameparamValue
- the param valueHttpRequest<T> setTemplateParam(String paramName, List<String> paramValue)
UriTemplate
.paramName
- the param nameparamValue
- the param valueHttpRequest<T> setTemplateParam(String paramName, Map<String,String> paramValue)
UriTemplate
.paramName
- the param nameparamValue
- the param valueHttpRequest<T> followRedirects(boolean value)
value
- true if redirections should be followedboolean followRedirects()
HttpRequest<T> proxy(ProxyOptions proxyOptions)
proxyOptions
- The proxy optionsProxyOptions proxy()
default HttpRequest<T> expect(java.util.function.Function<HttpResponse<Void>,ResponsePredicateResult> predicate)
predicate
.
Multiple predicates can be added.
predicate
- the predicateHttpRequest<T> expect(ResponsePredicate predicate)
predicate
.
Multiple predicates can be added.
predicate
- the predicateList<ResponsePredicate> expectations()
MultiMap queryParams()
Variables templateParams()
HttpRequest<T> copy()
HttpRequest<T> multipartMixed(boolean allow)
MultipartForm
having files sharing the same
file name.
true
.
false
if you want to achieve the behavior for HTML5.allow
- true
allows use of multipart mixed encodingboolean multipartMixed()
HttpRequest<T> traceOperation(String traceOperation)
traceOperation
- Name of operation to use in tracesString traceOperation()
void sendStream(ReadStream<Buffer> body, Handler<AsyncResult<HttpResponse<T>>> handler)
send(Handler)
but with an HTTP request body
stream.body
- the bodydefault Future<HttpResponse<T>> sendStream(ReadStream<Buffer> body)
body
- the bodysendStream(ReadStream, Handler)
void sendBuffer(Buffer body, Handler<AsyncResult<HttpResponse<T>>> handler)
send(Handler)
but with an HTTP request body
buffer.body
- the bodydefault Future<HttpResponse<T>> sendBuffer(Buffer body)
body
- the bodysendBuffer(Buffer, Handler)
void sendJsonObject(JsonObject body, Handler<AsyncResult<HttpResponse<T>>> handler)
send(Handler)
but with an HTTP request body
object encoded as json and the content type
set to application/json
.body
- the bodydefault Future<HttpResponse<T>> sendJsonObject(JsonObject body)
body
- the bodysendJsonObject(JsonObject, Handler)
void sendJson(Object body, Handler<AsyncResult<HttpResponse<T>>> handler)
send(Handler)
but with an HTTP request body
object encoded as json and the content type
set to application/json
.body
- the bodydefault Future<HttpResponse<T>> sendJson(Object body)
body
- the bodysendJson(Object, Handler)
void sendForm(MultiMap body, Handler<AsyncResult<HttpResponse<T>>> handler)
send(Handler)
but with an HTTP request body
multimap encoded as form and the content type
set to application/x-www-form-urlencoded
.
When the content type header is previously set to multipart/form-data
it will be used instead.
body
- the bodydefault Future<HttpResponse<T>> sendForm(MultiMap body)
body
- the bodysendForm(MultiMap, Handler)
void sendForm(MultiMap body, String charset, Handler<AsyncResult<HttpResponse<T>>> handler)
send(Handler)
but with an HTTP request body
multimap encoded as form and the content type
set to application/x-www-form-urlencoded
.
When the content type header is previously set to multipart/form-data
it will be used instead.
NOTE: the use of this method is strongly discouraged to use when the form is a application/x-www-form-urlencoded
encoded form since the charset to use must be UTF-8.
body
- the bodydefault Future<HttpResponse<T>> sendForm(MultiMap body, String charset)
body
- the bodycharset
- the charsetsendForm(MultiMap, String, Handler)
void sendMultipartForm(MultipartForm body, Handler<AsyncResult<HttpResponse<T>>> handler)
send(Handler)
but with an HTTP request body
multimap encoded as form and the content type
set to multipart/form-data
. You may use this method to send attributes and upload files.body
- the bodydefault Future<HttpResponse<T>> sendMultipartForm(MultipartForm body)
body
- the bodysendMultipartForm(MultipartForm, Handler)
void send(Handler<AsyncResult<HttpResponse<T>>> handler)
handler
will receive the response as an HttpResponse
.default Future<HttpResponse<T>> send()
send(Handler)
Copyright © 2023 Eclipse. All rights reserved.