public interface HttpClientRequest extends WriteStream<Buffer>, ReadStream<HttpClientResponse>
Represents a client-side HTTP request.<p>
Instances are created by an HttpClient instance, via one of the methods corresponding to the
specific HTTP methods, or the generic HttpClient.request(io.vertx.core.http.HttpMethod, java.lang.String) method.<p>
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, the end() method should be called.<p>
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.<p>
The headers of the request are actually sent either when the end() method is called, or, when the first
part of the body is written, whichever occurs first.<p>
This class supports both chunked and non-chunked HTTP.<p>
It implements WriteStream so it can be used with
Pump to pump data with flow control.<p>
An example of using this class is as follows:
<p>
<pre>
HttpClientRequest req = httpClient.post("/some-url", new Handler<HttpClientResponse>() { public void handle(HttpClientResponse response) { System.out.println("Got response: " + response.statusCode); } });
req.headers().put("some-header", "hello") .put("Content-Length", 5) .write(Buffer.newBuffer(new byte[]{1, 2, 3, 4, 5})) .write(Buffer.newBuffer(new byte[]{6, 7, 8, 9, 10})) .end();
</pre> Instances of HttpClientRequest are not thread-safe
| Modifier and Type | Method and Description |
|---|---|
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.<p>
You can then continue to write data to the request body and later end it. |
HttpClientRequest |
drainHandler(Handler<Void> handler)
Set a drain handler on the stream.
|
void |
end()
Ends the request.
|
void |
end(Buffer chunk)
Same as
end() but writes some data to the request body before ending. |
void |
end(String chunk)
Same as
end(Buffer) but writes a String with the default encoding |
void |
end(String chunk,
String enc)
Same as
end(Buffer) but writes a String with the specified encoding |
HttpClientRequest |
endHandler(Handler<Void> endHandler)
Set an end handler.
|
HttpClientRequest |
exceptionHandler(Handler<Throwable> handler)
Set an exception handler.
|
HttpClientRequest |
handler(Handler<HttpClientResponse> handler)
Set a data handler.
|
MultiMap |
headers() |
boolean |
isChunked() |
HttpMethod |
method()
The HTTP method for the request.
|
HttpClientRequest |
pause()
Pause the
ReadSupport. |
HttpClientRequest |
putHeader(CharSequence name,
CharSequence value) |
HttpClientRequest |
putHeader(CharSequence name,
Iterable<CharSequence> values) |
HttpClientRequest |
putHeader(String name,
Iterable<String> values)
Put an HTTP header - fluent API
|
HttpClientRequest |
putHeader(String name,
String value)
Put an HTTP header - fluent API
|
HttpClientRequest |
resume()
Resume reading.
|
HttpClientRequest |
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 |
setChunked(boolean chunked)
If chunked is true then the request will be set into HTTP chunked mode
|
HttpClientRequest |
setTimeout(long timeoutMs)
Set’s the amount of time after which if a response is not received TimeoutException()
will be sent to the exception handler of this request.
|
HttpClientRequest |
setWriteQueueMaxSize(int maxSize)
Set the maximum size of the write queue to
maxSize. |
String |
uri()
The uri of the request.
|
HttpClientRequest |
write(Buffer data)
Write some data to the stream.
|
HttpClientRequest |
write(String chunk)
Write a
String to the request body, encoded in UTF-8. |
HttpClientRequest |
write(String chunk,
String enc)
Write a
String to the request body, encoded using the encoding enc. |
writeQueueFullHttpClientRequest exceptionHandler(Handler<Throwable> handler)
StreamBaseSet an exception handler.
exceptionHandler in interface ReadStream<HttpClientResponse>exceptionHandler in interface StreamBaseexceptionHandler in interface WriteStream<Buffer>HttpClientRequest write(Buffer data)
WriteStreamWrite some data to the stream. The data is put on an internal write queue, and the write actually happens
asynchronously. To avoid running out of memory by putting too much on the write queue,
check the WriteStream.writeQueueFull() method before writing. This is done automatically if using a Pump.
write in interface WriteStream<Buffer>IllegalStateException - when no response handler is setHttpClientRequest setWriteQueueMaxSize(int maxSize)
WriteStreamSet the maximum size of the write queue to maxSize. You will still be able to write to the stream even
if there is more than maxSize bytes in the write queue. This is used as an indicator by classes such as
Pump to provide flow control.
setWriteQueueMaxSize in interface WriteStream<Buffer>HttpClientRequest drainHandler(Handler<Void> handler)
WriteStreamSet a drain handler on the stream. If the write queue is full, then the handler will be called when the write
queue has been reduced to maxSize / 2. See Pump for an example of this being used.
drainHandler in interface WriteStream<Buffer>HttpClientRequest handler(Handler<HttpClientResponse> handler)
ReadStreamSet a data handler. As data is read, the handler will be called with the data.
handler in interface ReadStream<HttpClientResponse>HttpClientRequest pause()
ReadStreamPause the ReadSupport. While it’s paused, no data will be sent to the dataHandler
pause in interface ReadStream<HttpClientResponse>HttpClientRequest resume()
ReadStreamResume reading. If the ReadSupport has been paused, reading will recommence on it.
resume in interface ReadStream<HttpClientResponse>HttpClientRequest endHandler(Handler<Void> endHandler)
ReadStreamSet an end handler. Once the stream has ended, and there is no more data to be read, this handler will be called.
endHandler in interface ReadStream<HttpClientResponse>HttpClientRequest setChunked(boolean chunked)
If chunked is true then the request will be set into HTTP chunked mode
chunked - boolean isChunked()
HttpMethod method()
The HTTP method for the request. One of GET, PUT, POST, DELETE, TRACE, CONNECT, OPTIONS or HEAD
String uri()
The uri of the request. For example http://www.somedomain.com/somepath/somemorepath/someresource.foo?someparam=32&someotherparam=x
MultiMap headers()
HttpClientRequest putHeader(String name, String value)
Put an HTTP header - fluent API
name - The header namevalue - The header valueHttpClientRequest putHeader(CharSequence name, CharSequence value)
HttpClientRequest putHeader(String name, Iterable<String> values)
Put an HTTP header - fluent API
name - The header namevalues - The header valuesHttpClientRequest putHeader(CharSequence name, Iterable<CharSequence> values)
HttpClientRequest write(String chunk)
Write a String to the request body, encoded in UTF-8.
IllegalStateException - when no response handler is setHttpClientRequest write(String chunk, String enc)
Write a String to the request body, encoded using the encoding enc.
IllegalStateException - when no response handler is setHttpClientRequest 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.<p>
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 sendHead()
Forces the head of the request to be written before 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 setvoid end(String chunk)
Same as end(Buffer) but writes a String with the default encoding
IllegalStateException - when no response handler is setvoid end(String chunk, String enc)
Same as end(Buffer) but writes a String with the specified encoding
IllegalStateException - when no response handler is setvoid end(Buffer chunk)
Same as 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 set
IllegalStateException - when no response handler is setvoid end()
Ends the request. If no data has been written to the request body, and sendHead() has not been called then
the actual request won’t get written until this method gets called.<p>
Once the request has ended, it cannot be used any more, and if keep alive is true the underlying connection will
be returned to the HttpClient pool so it can be assigned to another request.
IllegalStateException - when no response handler is setHttpClientRequest setTimeout(long timeoutMs)
Set’s the amount of time after which if a response is not received TimeoutException() will be sent to the exception handler of this request. Calling this method more than once has the effect of canceling any existing timeout and starting the timeout from scratchpad.
timeoutMs - The quantity of time in milliseconds.Copyright © 2014. All Rights Reserved.