public interface HttpClientRequest extends WriteStream<Buffer>
Instances are created by an HttpClient instance, via one of the methods corresponding to the
specific HTTP methods, or the generic request methods. On creation the request will not have been written to the
wire.
Once a request has been obtained, headers can be set on it, and data can be written to its body if required. Once
you are ready to send the request, one of the end() methods should be called.
Nothing is actually sent until the request has been internally assigned an HTTP connection.
The HttpClient instance will return an instance of this class immediately, even if there are no HTTP
connections available in the pool. Any requests sent before a connection is assigned will be queued
internally and actually sent when an HTTP connection becomes available from the pool.
The headers of the request are queued for writing either when the end() method is called, or, when the first
part of the body is written, whichever occurs first.
This class supports both chunked and non-chunked HTTP.
It implements WriteStream so it can be used with
Pipe to pipe data with flow control.
An example of using this class is as follows:
| Modifier and Type | Method and Description |
|---|---|
String |
absoluteURI() |
HttpClientRequest |
authority(HostAndPort authority)
Override the request authority, when using HTTP/1.x this overrides the request
host header, when using
HTTP/2 this sets the authority pseudo header. |
Future<HttpClientResponse> |
connect()
Like
connect(Handler) but returns a Future of the asynchronous result |
void |
connect(Handler<AsyncResult<HttpClientResponse>> handler)
Create an HTTP tunnel to the server.
|
HttpConnection |
connection() |
HttpClientRequest |
continueHandler(Handler<Void> handler)
If you send an HTTP request with the header
Expect set to the value 100-continue
and the server responds with an interim HTTP response with a status code of 100 and a Continue handler
has been set using this method, then the handler will be called. |
HttpClientRequest |
drainHandler(Handler<Void> handler)
Set a drain handler on the stream.
|
HttpClientRequest |
earlyHintsHandler(Handler<MultiMap> handler)
If the server responds with an interim HTTP response with a status code of
103 and a Early Hints handler
has been set using this method, then the handler will be called. |
Future<Void> |
end()
Ends the request.
|
Future<Void> |
end(Buffer chunk)
Same as
end() but writes some data to the request body before ending. |
void |
end(Buffer chunk,
Handler<AsyncResult<Void>> handler)
Same as
end(String) but with an handler called when the operation completes |
void |
end(Handler<AsyncResult<Void>> handler)
Same as
end() but with an handler called when the operation completes |
Future<Void> |
end(String chunk)
Same as
end(Buffer) but writes a String in UTF-8 encoding |
void |
end(String chunk,
Handler<AsyncResult<Void>> handler)
Same as
end(String) but with an handler called when the operation completes |
Future<Void> |
end(String chunk,
String enc)
Same as
end(Buffer) but writes a String with the specified encoding |
void |
end(String chunk,
String enc,
Handler<AsyncResult<Void>> handler)
Same as
end(String,String) but with an handler called when the operation completes |
HttpClientRequest |
exceptionHandler(Handler<Throwable> handler)
Set an exception handler on the write stream.
|
String |
getHost()
Deprecated.
|
int |
getMaxRedirects() |
HttpMethod |
getMethod()
The HTTP method for the request.
|
int |
getPort()
Deprecated.
|
StreamPriority |
getStreamPriority() |
String |
getURI() |
MultiMap |
headers() |
default HttpClientRequest |
idleTimeout(long timeout)
Sets the amount of time after which, if the request does not return any data within the timeout period,
the request/response is closed and the related futures are failed with a
TimeoutException,
e.g. |
boolean |
isChunked() |
boolean |
isFollowRedirects() |
int |
numberOfRedirections() |
String |
path() |
HttpClientRequest |
pushHandler(Handler<HttpClientRequest> handler)
Set a push handler for this request.
The handler is called when the client receives a push promise from the server.
|
HttpClientRequest |
putHeader(CharSequence name,
CharSequence value)
Like
putHeader(String, String) but using CharSequence |
HttpClientRequest |
putHeader(CharSequence name,
Iterable<CharSequence> values)
Like
putHeader(String, Iterable) but using CharSequence |
HttpClientRequest |
putHeader(String name,
Iterable<String> values)
Put an HTTP header with multiple values
|
HttpClientRequest |
putHeader(String name,
String value)
Put an HTTP header
|
String |
query() |
HttpClientRequest |
redirectHandler(java.util.function.Function<HttpClientResponse,Future<HttpClientRequest>> handler) |
default boolean |
reset()
Reset this stream with the error code
0. |
boolean |
reset(long code)
Reset this request:
for HTTP/2, this performs send an HTTP/2 reset frame with the specified error
code
for HTTP/1.x, this closes the connection when the current request is inflight
When the request has not yet been sent, the request will be aborted and false is returned as indicator. |
boolean |
reset(long code,
Throwable cause)
Reset this request:
for HTTP/2, send an HTTP/2 reset frame with the specified error
code
for HTTP/1.x, close the connection when the current request is inflight
When the request has not yet been sent, the request will be aborted and false is returned as indicator. |
Future<HttpClientResponse> |
response() |
HttpClientRequest |
response(Handler<AsyncResult<HttpClientResponse>> handler)
Set a callback for the associated
HttpClientResponse. |
default Future<HttpClientResponse> |
send()
Like
send(Handler) but returns a Future of the asynchronous result |
default Future<HttpClientResponse> |
send(Buffer body)
Like
send(Buffer, Handler) but returns a Future of the asynchronous result |
default void |
send(Buffer body,
Handler<AsyncResult<HttpClientResponse>> handler)
Send the request with a buffer
body. |
default void |
send(Handler<AsyncResult<HttpClientResponse>> handler)
Send the request with an empty body.
|
default Future<HttpClientResponse> |
send(ReadStream<Buffer> body)
Like
send(ReadStream, Handler) but returns a Future of the asynchronous result |
default void |
send(ReadStream<Buffer> body,
Handler<AsyncResult<HttpClientResponse>> handler)
Send the request with a stream
body. |
default Future<HttpClientResponse> |
send(String body)
Like
send(String, Handler) but returns a Future of the asynchronous result |
default void |
send(String body,
Handler<AsyncResult<HttpClientResponse>> handler)
Send the request with a string
body. |
Future<Void> |
sendHead()
Forces the head of the request to be written before
end() is called on the request or any data is
written to it. |
HttpClientRequest |
sendHead(Handler<AsyncResult<Void>> completionHandler)
Like
sendHead() but with an handler after headers have been sent. |
HttpClientRequest |
setChunked(boolean chunked)
If chunked is true then the request will be set into HTTP chunked mode
|
HttpClientRequest |
setFollowRedirects(boolean followRedirects)
Set the request to follow HTTP redirects up to
HttpClientOptions.getMaxRedirects(). |
HttpClientRequest |
setHost(String host)
Deprecated.
instead use
authority(HostAndPort) |
HttpClientRequest |
setMaxRedirects(int maxRedirects)
Set the max number of HTTP redirects this request will follow.
|
HttpClientRequest |
setMethod(HttpMethod method)
Set the HTTP method for this request.
|
HttpClientRequest |
setPort(int port)
Deprecated.
instead use
authority(HostAndPort) |
default HttpClientRequest |
setStreamPriority(StreamPriority streamPriority)
Sets the priority of the associated stream.
|
HttpClientRequest |
setTimeout(long timeout)
Deprecated.
instead use
idleTimeout(long) |
HttpClientRequest |
setURI(String uri)
Set the request uri.
|
HttpClientRequest |
setWriteQueueMaxSize(int maxSize)
Set the maximum size of the write queue to
maxSize. |
default int |
streamId() |
String |
traceOperation() |
HttpClientRequest |
traceOperation(String op)
Set the trace operation of this request.
|
HttpVersion |
version() |
Future<Void> |
write(String chunk)
Write a
String to the request body, encoded as UTF-8. |
void |
write(String chunk,
Handler<AsyncResult<Void>> handler)
Same as
write(String) but with an handler called when the operation completes |
Future<Void> |
write(String chunk,
String enc)
Write a
String to the request body, encoded using the encoding enc. |
void |
write(String chunk,
String enc,
Handler<AsyncResult<Void>> handler)
Same as
write(String,String) but with an handler called when the operation completes |
default HttpClientRequest |
writeCustomFrame(HttpFrame frame)
Like
writeCustomFrame(int, int, Buffer) but with an HttpFrame. |
HttpClientRequest |
writeCustomFrame(int type,
int flags,
Buffer payload)
Write an HTTP/2 frame to the request, allowing to extend the HTTP/2 protocol.
|
write, write, writeQueueFullHttpClientRequest exceptionHandler(Handler<Throwable> handler)
WriteStreamexceptionHandler in interface StreamBaseexceptionHandler in interface WriteStream<Buffer>handler - the exception handlerHttpClientRequest setWriteQueueMaxSize(int maxSize)
WriteStreammaxSize. You will still be able to write to the stream even
if there is more than maxSize items in the write queue. This is used as an indicator by classes such as
Pipe to provide flow control.
The value is defined by the implementation of the stream, e.g in bytes for a
NetSocket, etc...setWriteQueueMaxSize in interface WriteStream<Buffer>maxSize - the max size of the write streamHttpClientRequest drainHandler(Handler<Void> handler)
WriteStreamPipe for an example of this being used.
The stream implementation defines when the drain handler, for example it could be when the queue size has been
reduced to maxSize / 2.
drainHandler in interface WriteStream<Buffer>handler - the handlerHttpClientRequest authority(HostAndPort authority)
host header, when using
HTTP/2 this sets the authority pseudo header. When the port is a negative value, the default
scheme port will be used.
The default request authority is the server host and port when connecting to the server.
authority - override the request authority@Deprecated HttpClientRequest setHost(String host)
authority(HostAndPort)host header or HTTP/2 authority pseudo header
The initial value is the same as the server socket address host.
Keep in mind that changing this value won't change the actual server socket address for this request.
host - the host part of the HTTP/1.1 host header or HTTP/2 authority pseudo header@Deprecated String getHost()
host header or HTTP/2 authority pseudo header@Deprecated HttpClientRequest setPort(int port)
authority(HostAndPort)host header or HTTP/2 authority pseudo header
Keep in mind that this won't change the actual server socket address for this request.
The initial value is the same than the server socket address port.
port - the port part of the HTTP/1.1 host header or HTTP/2 authority pseudo header@Deprecated int getPort()
host header or HTTP/2 authority pseudo headerHttpClientRequest setFollowRedirects(boolean followRedirects)
HttpClientOptions.getMaxRedirects().followRedirects - true to follow HTTP redirectsboolean isFollowRedirects()
HttpClientRequest setMaxRedirects(int maxRedirects)
0 which means
no redirects.maxRedirects - the number of HTTP redirect to followint getMaxRedirects()
int numberOfRedirections()
HttpClientRequest setChunked(boolean chunked)
chunked - true if chunked encodingboolean isChunked()
HttpMethod getMethod()
HttpClientRequest setMethod(HttpMethod method)
method - the HTTP methodString absoluteURI()
String getURI()
HttpClientRequest setURI(String uri)
uri - the request uriString path()
String query()
MultiMap headers()
HttpClientRequest putHeader(String name, String value)
name - The header namevalue - The header valueHttpClientRequest putHeader(CharSequence name, CharSequence value)
putHeader(String, String) but using CharSequenceHttpClientRequest putHeader(String name, Iterable<String> values)
name - The header namevalues - The header valuesHttpClientRequest putHeader(CharSequence name, Iterable<CharSequence> values)
putHeader(String, Iterable) but using CharSequenceHttpClientRequest traceOperation(String op)
op - the operationString traceOperation()
HttpVersion version()
Future<Void> write(String chunk)
String to the request body, encoded as UTF-8.chunk - the data chunkIllegalStateException - when no response handler is setvoid write(String chunk, Handler<AsyncResult<Void>> handler)
write(String) but with an handler called when the operation completesFuture<Void> write(String chunk, String enc)
String to the request body, encoded using the encoding enc.chunk - the data chunkenc - the encodingIllegalStateException - when no response handler is setvoid write(String chunk, String enc, Handler<AsyncResult<Void>> handler)
write(String,String) but with an handler called when the operation completesHttpClientRequest continueHandler(Handler<Void> handler)
Expect set to the value 100-continue
and the server responds with an interim HTTP response with a status code of 100 and a Continue handler
has been set using this method, then the handler will be called.
You can then continue to write data to the request body and later end it. This is normally used in conjunction with
the sendHead() method to force the request header to be written before the request has ended.
HttpClientRequest earlyHintsHandler(Handler<MultiMap> handler)
103 and a Early Hints handler
has been set using this method, then the handler will be called.HttpClientRequest redirectHandler(java.util.function.Function<HttpClientResponse,Future<HttpClientRequest>> handler)
Future<Void> sendHead()
end() is called on the request or any data is
written to it.
This is normally used to implement HTTP 100-continue handling, see continueHandler(io.vertx.core.Handler) for
more information.
IllegalStateException - when no response handler is setHttpClientRequest sendHead(Handler<AsyncResult<Void>> completionHandler)
sendHead() but with an handler after headers have been sent. The handler will be called with
the HttpVersion if it can be determined or null otherwise.void connect(Handler<AsyncResult<HttpClientResponse>> handler)
Send HTTP request headers to the server, then configures the transport to exchange raw buffers when the server replies with an appropriate response:
200 for HTTP CONNECT method101 for HTTP/1.1 GET with Upgrade connection header The handler is called after response headers are received.
Use HttpClientResponse.netSocket() to get a NetSocket for interacting
more conveniently with the server.
HTTP/1.1 pipe-lined requests are not supported.f
handler - the response completion handlerFuture<HttpClientResponse> connect()
connect(Handler) but returns a Future of the asynchronous resultHttpClientRequest response(Handler<AsyncResult<HttpClientResponse>> handler)
HttpClientResponse.
This method does not modify the current request being sent.
handler - the completion handlerFuture<HttpClientResponse> response()
HttpClientResponse, see response(Handler)default void send(Handler<AsyncResult<HttpClientResponse>> handler)
handler - the completion handler for the HttpClientResponsedefault Future<HttpClientResponse> send()
send(Handler) but returns a Future of the asynchronous resultdefault void send(String body, Handler<AsyncResult<HttpClientResponse>> handler)
body.handler - the completion handler for the HttpClientResponsedefault Future<HttpClientResponse> send(String body)
send(String, Handler) but returns a Future of the asynchronous resultdefault void send(Buffer body, Handler<AsyncResult<HttpClientResponse>> handler)
body.handler - the completion handler for the HttpClientResponsedefault Future<HttpClientResponse> send(Buffer body)
send(Buffer, Handler) but returns a Future of the asynchronous resultdefault void send(ReadStream<Buffer> body, Handler<AsyncResult<HttpClientResponse>> handler)
body.
If the HttpHeaders.CONTENT_LENGTH is set then the request assumes this is the
length of the {stream}, otherwise the request will set a chunked HttpHeaders.CONTENT_ENCODING.
handler - the completion handler for the HttpClientResponsedefault Future<HttpClientResponse> send(ReadStream<Buffer> body)
send(ReadStream, Handler) but returns a Future of the asynchronous resultFuture<Void> end(String chunk)
end(Buffer) but writes a String in UTF-8 encodingchunk - the data chunkIllegalStateException - when no response handler is setvoid end(String chunk, Handler<AsyncResult<Void>> handler)
end(String) but with an handler called when the operation completesFuture<Void> end(String chunk, String enc)
end(Buffer) but writes a String with the specified encodingchunk - the data chunkenc - the encodingIllegalStateException - when no response handler is setvoid end(String chunk, String enc, Handler<AsyncResult<Void>> handler)
end(String,String) but with an handler called when the operation completesFuture<Void> end(Buffer chunk)
end() but writes some data to the request body before ending. If the request is not chunked and
no other data has been written then the Content-Length header will be automatically setend in interface WriteStream<Buffer>chunk - the data to writeIllegalStateException - when no response handler is setvoid end(Buffer chunk, Handler<AsyncResult<Void>> handler)
end(String) but with an handler called when the operation completesend in interface WriteStream<Buffer>Future<Void> end()
sendHead() has not been called then
the actual request won't get written until this method gets called.
Once the request has ended, it cannot be used any more,
end in interface WriteStream<Buffer>IllegalStateException - when no response handler is setvoid end(Handler<AsyncResult<Void>> handler)
end() but with an handler called when the operation completesend in interface WriteStream<Buffer>@Deprecated HttpClientRequest setTimeout(long timeout)
idleTimeout(long)idleTimeout(long) but with a confusing name (hence the deprecation).default HttpClientRequest idleTimeout(long timeout)
TimeoutException,
e.g. Future<HttpClientResponse> or Future<Buffer> response body.timeout - the amount of time in milliseconds.HttpClientRequest pushHandler(Handler<HttpClientRequest> handler)
HttpClientRequest, the following methods can be called:
In addition the handler should call the response(Handler) method to set an handler to
process the response.handler - the handlerdefault boolean reset()
0.reset(long)boolean reset(long code)
codecode - the error codetrue when reset has been performedboolean reset(long code,
Throwable cause)
codefalse is returned as indicator.
code - the error codecause - an optional cause that can be attached to the error codeHttpConnection connection()
HttpConnection associated with this requestHttpClientRequest writeCustomFrame(int type, int flags, Buffer payload)
The frame is sent immediatly and is not subject to flow control.
This method must be called after the request headers have been sent and only for the protocol HTTP/2.
The sendHead(Handler) should be used for this purpose.
type - the 8-bit frame typeflags - the 8-bit frame flagspayload - the frame payloaddefault int streamId()
default HttpClientRequest writeCustomFrame(HttpFrame frame)
writeCustomFrame(int, int, Buffer) but with an HttpFrame.frame - the frame to writedefault HttpClientRequest setStreamPriority(StreamPriority streamPriority)
streamPriority - the priority of this request's streamStreamPriority getStreamPriority()
nullCopyright © 2024 Eclipse. All rights reserved.