Interface HttpClientRequest
-
- All Superinterfaces:
StreamBase,WriteStream<Buffer>
public interface HttpClientRequest extends WriteStream<Buffer>
Represents a client-side HTTP request.Instances are created by an
HttpClientinstance, 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
HttpClientinstance 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
WriteStreamso it can be used withPipeto pipe data with flow control.An example of using this class is as follows:
- Author:
- Tim Fox
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description StringabsoluteURI()HttpClientRequestauthority(HostAndPort authority)Override the request authority, when using HTTP/1.x this overrides the requesthostheader, when using HTTP/2 this sets theauthoritypseudo header.Future<HttpClientResponse>connect()Create an HTTP tunnel to the server.HttpConnectionconnection()HttpClientRequestcontinueHandler(Handler<Void> handler)If you send an HTTP request with the headerExpectset to the value100-continueand the server responds with an interim HTTP response with a status code of100and a Continue handler has been set using this method, then thehandlerwill be called.HttpClientRequestdrainHandler(Handler<Void> handler)Set a drain handler on the stream.HttpClientRequestearlyHintsHandler(Handler<MultiMap> handler)If the server responds with an interim HTTP response with a status code of103and a Early Hints handler has been set using this method, then thehandlerwill be called.Future<Void>end()Ends the request.Future<Void>end(Buffer chunk)Same asend()but writes some data to the request body before ending.Future<Void>end(String chunk)Same asend(Buffer)but writes a String in UTF-8 encodingFuture<Void>end(String chunk, String enc)Same asend(Buffer)but writes a String with the specified encodingHttpClientRequestexceptionHandler(Handler<Throwable> handler)Set an exception handler on the write stream.intgetMaxRedirects()HttpMethodgetMethod()The HTTP method for the request.StreamPrioritygetStreamPriority()StringgetURI()MultiMapheaders()HttpClientRequestidleTimeout(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 aTimeoutException, e.g.booleanisChunked()booleanisFollowRedirects()intnumberOfRedirections()Stringpath()HttpClientRequestpushHandler(Handler<HttpClientRequest> handler)Set a push handler for this request.HttpClientRequestputHeader(CharSequence name, CharSequence value)LikeputHeader(String, String)but using CharSequenceHttpClientRequestputHeader(CharSequence name, Iterable<CharSequence> values)LikeputHeader(String, Iterable)but using CharSequenceHttpClientRequestputHeader(String name, Iterable<String> values)Put an HTTP header with multiple valuesHttpClientRequestputHeader(String name, String value)Put an HTTP headerStringquery()HttpClientRequestredirectHandler(Function<HttpClientResponse,Future<HttpClientRequest>> handler)default Future<Void>reset()Reset this stream with the error code0.Future<Void>reset(long code)Reset this request:Future<Void>reset(long code, Throwable cause)Reset this request:Future<HttpClientResponse>response()default Future<HttpClientResponse>send()Send the request with an empty body.default Future<HttpClientResponse>send(Buffer body)Send the request with a bufferbody.Future<HttpClientResponse>send(ClientForm form)Likesend()but with aform.default Future<HttpClientResponse>send(ReadStream<Buffer> body)Send the request with a streambody.default Future<HttpClientResponse>send(String body)Send the request with a stringbody.Future<Void>sendHead()Forces the head of the request to be written beforeend()is called on the request or any data is written to it.HttpClientRequestsetChunked(boolean chunked)If chunked is true then the request will be set into HTTP chunked modeHttpClientRequestsetFollowRedirects(boolean followRedirects)Set the request to follow HTTP redirects up toHttpClientOptions.getMaxRedirects().HttpClientRequestsetMaxRedirects(int maxRedirects)Set the max number of HTTP redirects this request will follow.HttpClientRequestsetMethod(HttpMethod method)Set the HTTP method for this request.default HttpClientRequestsetStreamPriority(StreamPriority streamPriority)Sets the priority of the associated stream.HttpClientRequestsetURI(String uri)Set the request uri.HttpClientRequestsetWriteQueueMaxSize(int maxSize)Set the maximum size of the write queue tomaxSize.default intstreamId()StringtraceOperation()HttpClientRequesttraceOperation(String op)Set the trace operation of this request.HttpVersionversion()Future<Void>write(String chunk)Write aStringto the request body, encoded as UTF-8.Future<Void>write(String chunk, String enc)Write aStringto the request body, encoded using the encodingenc.Future<Void>writeCustomFrame(int type, int flags, Buffer payload)Write an HTTP/2 frame to the request, allowing to extend the HTTP/2 protocol.default Future<Void>writeCustomFrame(HttpFrame frame)LikewriteCustomFrame(int, int, Buffer)but with anHttpFrame.-
Methods inherited from interface io.vertx.core.streams.WriteStream
write, writeQueueFull
-
-
-
-
Method Detail
-
exceptionHandler
HttpClientRequest exceptionHandler(Handler<Throwable> handler)
Description copied from interface:WriteStreamSet an exception handler on the write stream.- Specified by:
exceptionHandlerin interfaceStreamBase- Specified by:
exceptionHandlerin interfaceWriteStream<Buffer>- Parameters:
handler- the exception handler- Returns:
- a reference to this, so the API can be used fluently
-
setWriteQueueMaxSize
HttpClientRequest setWriteQueueMaxSize(int maxSize)
Description copied from interface:WriteStreamSet the maximum size of the write queue tomaxSize. You will still be able to write to the stream even if there is more thanmaxSizeitems in the write queue. This is used as an indicator by classes such asPipeto provide flow control. The value is defined by the implementation of the stream, e.g in bytes for aNetSocket, etc...- Specified by:
setWriteQueueMaxSizein interfaceWriteStream<Buffer>- Parameters:
maxSize- the max size of the write stream- Returns:
- a reference to this, so the API can be used fluently
-
drainHandler
HttpClientRequest drainHandler(Handler<Void> handler)
Description copied from interface:WriteStreamSet a drain handler on the stream. If the write queue is full, then the handler will be called when the write queue is ready to accept buffers again. SeePipefor 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.- Specified by:
drainHandlerin interfaceWriteStream<Buffer>- Parameters:
handler- the handler- Returns:
- a reference to this, so the API can be used fluently
-
authority
HttpClientRequest authority(HostAndPort authority)
Override the request authority, when using HTTP/1.x this overrides the requesthostheader, when using HTTP/2 this sets theauthoritypseudo 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.
- Parameters:
authority- override the request authority- Returns:
- a reference to this, so the API can be used fluently
-
setFollowRedirects
HttpClientRequest setFollowRedirects(boolean followRedirects)
Set the request to follow HTTP redirects up toHttpClientOptions.getMaxRedirects().- Parameters:
followRedirects-trueto follow HTTP redirects- Returns:
- a reference to this, so the API can be used fluently
-
isFollowRedirects
boolean isFollowRedirects()
- Returns:
- whether HTTP redirections should be followed
-
setMaxRedirects
HttpClientRequest setMaxRedirects(int maxRedirects)
Set the max number of HTTP redirects this request will follow. The default is0which means no redirects.- Parameters:
maxRedirects- the number of HTTP redirect to follow- Returns:
- a reference to this, so the API can be used fluently
-
getMaxRedirects
int getMaxRedirects()
- Returns:
- the maximum number of HTTP redirections to follow
-
numberOfRedirections
int numberOfRedirections()
- Returns:
- the number of followed redirections for the current HTTP request
-
setChunked
HttpClientRequest setChunked(boolean chunked)
If chunked is true then the request will be set into HTTP chunked mode- Parameters:
chunked- true if chunked encoding- Returns:
- a reference to this, so the API can be used fluently
-
isChunked
boolean isChunked()
- Returns:
- Is the request chunked?
-
getMethod
HttpMethod getMethod()
The HTTP method for the request.
-
setMethod
HttpClientRequest setMethod(HttpMethod method)
Set the HTTP method for this request.- Parameters:
method- the HTTP method- Returns:
- a reference to this, so the API can be used fluently
-
absoluteURI
String absoluteURI()
- Returns:
- the absolute URI corresponding to the HTTP request
-
getURI
String getURI()
- Returns:
- The URI of the request.
-
setURI
HttpClientRequest setURI(String uri)
Set the request uri.- Parameters:
uri- the request uri- Returns:
- a reference to this, so the API can be used fluently
-
path
String path()
- Returns:
- The path part of the uri. For example /somepath/somemorepath/someresource.foo
-
query
String query()
- Returns:
- the query part of the uri. For example someparam=32&someotherparam=x
-
headers
MultiMap headers()
- Returns:
- The HTTP headers
-
putHeader
HttpClientRequest putHeader(String name, String value)
Put an HTTP header- Parameters:
name- The header namevalue- The header value- Returns:
- a reference to this, so the API can be used fluently
-
putHeader
HttpClientRequest putHeader(CharSequence name, CharSequence value)
LikeputHeader(String, String)but using CharSequence
-
putHeader
HttpClientRequest putHeader(String name, Iterable<String> values)
Put an HTTP header with multiple values- Parameters:
name- The header namevalues- The header values- Returns:
-
putHeader
HttpClientRequest putHeader(CharSequence name, Iterable<CharSequence> values)
LikeputHeader(String, Iterable)but using CharSequence
-
traceOperation
HttpClientRequest traceOperation(String op)
Set the trace operation of this request.- Parameters:
op- the operation- Returns:
-
traceOperation
String traceOperation()
- Returns:
- the trace operation of this request
-
version
HttpVersion version()
- Returns:
- the HTTP version for this request
-
write
Future<Void> write(String chunk)
Write aStringto the request body, encoded as UTF-8.- Parameters:
chunk- the data chunk- Returns:
- a future completed with the result
- Throws:
IllegalStateException- when no response handler is set
-
write
Future<Void> write(String chunk, String enc)
Write aStringto the request body, encoded using the encodingenc.- Parameters:
chunk- the data chunkenc- the encoding- Returns:
- a future completed with the result
- Throws:
IllegalStateException- when no response handler is set
-
continueHandler
HttpClientRequest continueHandler(Handler<Void> handler)
If you send an HTTP request with the headerExpectset to the value100-continueand the server responds with an interim HTTP response with a status code of100and a Continue handler has been set using this method, then thehandlerwill 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.- Returns:
- a reference to this, so the API can be used fluently
-
earlyHintsHandler
HttpClientRequest earlyHintsHandler(Handler<MultiMap> handler)
If the server responds with an interim HTTP response with a status code of103and a Early Hints handler has been set using this method, then thehandlerwill be called.- Returns:
- a reference to this, so the API can be used fluently
-
redirectHandler
HttpClientRequest redirectHandler(Function<HttpClientResponse,Future<HttpClientRequest>> handler)
-
sendHead
Future<Void> sendHead()
Forces the head of the request to be written beforeend()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.- Returns:
- a future notified when the
HttpVersionif it can be determined ornullotherwise - Throws:
IllegalStateException- when no response handler is set
-
connect
Future<HttpClientResponse> connect()
Create an HTTP tunnel to the server.Send HTTP request headers to the server, then configures the transport to exchange raw buffers when the server replies with an appropriate response:
200for HTTPCONNECTmethod101for HTTP/1.1GETwithUpgradeconnectionheader
The
handleris called after response headers are received.Use
HttpClientResponse.netSocket()to get aNetSocketfor interacting more conveniently with the server.HTTP/1.1 pipe-lined requests are not supported.f
- Returns:
- a future notified with the server response
-
response
Future<HttpClientResponse> response()
- Returns:
- a future of the
HttpClientResponse, this method does not modify the current request being sent.
-
send
default Future<HttpClientResponse> send()
Send the request with an empty body.- Returns:
- a future notified when the HTTP response is available
-
send
default Future<HttpClientResponse> send(String body)
Send the request with a stringbody.- Returns:
- a future notified when the HTTP response is available
-
send
default Future<HttpClientResponse> send(Buffer body)
Send the request with a bufferbody.- Returns:
- a future notified when the HTTP response is available
-
send
Future<HttpClientResponse> send(ClientForm form)
Likesend()but with aform. The content will be set toapplication/x-www-form-urlencodedormultipart/form-dataaccording to the nature of the form.- Parameters:
form- the form to send- Returns:
- a future notified when the HTTP response is available
-
send
default Future<HttpClientResponse> send(ReadStream<Buffer> body)
Send the request with a streambody.If the
HttpHeaders.CONTENT_LENGTHis set then the request assumes this is the length of the {stream}, otherwise the request will set a chunkedHttpHeaders.CONTENT_ENCODING.- Returns:
- a future notified when the HTTP response is available
-
end
Future<Void> end(String chunk)
Same asend(Buffer)but writes a String in UTF-8 encoding- Parameters:
chunk- the data chunk- Returns:
- a future completed with the result
- Throws:
IllegalStateException- when no response handler is set
-
end
Future<Void> end(String chunk, String enc)
Same asend(Buffer)but writes a String with the specified encoding- Parameters:
chunk- the data chunkenc- the encoding- Returns:
- a future completed with the result
- Throws:
IllegalStateException- when no response handler is set
-
end
Future<Void> end(Buffer chunk)
Same asend()but writes some data to the request body before ending. If the request is not chunked and no other data has been written then theContent-Lengthheader will be automatically set- Specified by:
endin interfaceWriteStream<Buffer>- Parameters:
chunk- the data to write- Returns:
- a future completed with the result
- Throws:
IllegalStateException- when no response handler is set
-
end
Future<Void> end()
Ends the request. If no data has been written to the request body, andsendHead()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,
- Specified by:
endin interfaceWriteStream<Buffer>- Returns:
- a future completed with the result
- Throws:
IllegalStateException- when no response handler is set
-
idleTimeout
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 aTimeoutException, e.g.Future<HttpClientResponse>orFuture<Buffer>response body.- Parameters:
timeout- the amount of time in milliseconds.- Returns:
- a reference to this, so the API can be used fluently
-
pushHandler
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. The handler can be called multiple times, for each push promise. The handler is called with a read-onlyHttpClientRequest, the following methods can be called: In addition the handler should call theresponse()method to set an handler to process the response.- Parameters:
handler- the handler- Returns:
- a reference to this, so the API can be used fluently
-
reset
default Future<Void> reset()
Reset this stream with the error code0.- See Also:
reset(long)
-
reset
Future<Void> 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
- Parameters:
code- the error code- Returns:
truewhen reset has been performed
- for HTTP/2, this performs send an HTTP/2 reset frame with the specified error
-
reset
Future<Void> 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
falseis returned as indicator.- Parameters:
code- the error codecause- an optional cause that can be attached to the error code- Returns:
- true when reset has been performed
- for HTTP/2, send an HTTP/2 reset frame with the specified error
-
connection
HttpConnection connection()
- Returns:
- the
HttpConnectionassociated with this request
-
writeCustomFrame
Future<Void> writeCustomFrame(int type, int flags, Buffer payload)
Write an HTTP/2 frame to the request, allowing to extend the HTTP/2 protocol.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()should be used for this purpose.- Parameters:
type- the 8-bit frame typeflags- the 8-bit frame flagspayload- the frame payload- Returns:
- a reference to this, so the API can be used fluently
-
streamId
default int streamId()
- Returns:
- the id of the stream of this response, -1 when it is not yet determined, i.e the request has not been yet sent or it is not supported HTTP/1.x
-
writeCustomFrame
default Future<Void> writeCustomFrame(HttpFrame frame)
LikewriteCustomFrame(int, int, Buffer)but with anHttpFrame.- Parameters:
frame- the frame to write
-
setStreamPriority
default HttpClientRequest setStreamPriority(StreamPriority streamPriority)
Sets the priority of the associated stream. This is not implemented for HTTP/1.x.- Parameters:
streamPriority- the priority of this request's stream
-
getStreamPriority
StreamPriority getStreamPriority()
- Returns:
- the priority of the associated HTTP/2 stream for HTTP/2 otherwise
null
-
-