HttpClientRequest (Vert.x Core 3.3.0.CR1 API)

All Superinterfaces:

ReadStream<HttpClientResponse>, StreamBase, WriteStream<Buffer>
```
public interface HttpClientRequest
extends WriteStream<Buffer>, ReadStream<HttpClientResponse>
```
Represents a client-side HTTP request.
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 Pump to pump 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 and Description
`HttpConnection`	`connection()`
`HttpClientRequest`	`connectionHandler(Handler<HttpConnection> handler)` Set a connection handler called when an HTTP connection has been established.
`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.
`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 in UTF-8 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 on the write stream.
`String`	`getHost()`
`String`	`getRawMethod()`
`HttpClientRequest`	`handler(Handler<HttpClientResponse> handler)` Set a data handler.
`MultiMap`	`headers()`
`boolean`	`isChunked()`
`HttpMethod`	`method()` The HTTP method for the request.
`String`	`path()`
`HttpClientRequest`	`pause()` Pause the `ReadSupport`.
`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()`
`default void`	`reset()` Reset this stream with the error code `0`.
`void`	`reset(long code)` Reset this stream with the error `code`.
`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`	`sendHead(Handler<HttpVersion> 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`	`setHost(String host)` Set the request host. For HTTP2 it sets the :authority pseudo header otherwise it sets the Host header
`HttpClientRequest`	`setRawMethod(String method)` Set the value the method to send when the method `HttpMethod.OTHER` is used.
`HttpClientRequest`	`setTimeout(long timeoutMs)` Set's the amount of time after which if the request does not return any data within the timeout period an `TimeoutException` will be passed to the exception handler (if provided) and the request will be closed.
`HttpClientRequest`	`setWriteQueueMaxSize(int maxSize)` Set the maximum size of the write queue to `maxSize`.
`default int`	`streamId()`
`String`	`uri()`
`HttpClientRequest`	`write(Buffer data)` Write some data to the stream.
`HttpClientRequest`	`write(String chunk)` Write a `String` to the request body, encoded as UTF-8.
`HttpClientRequest`	`write(String chunk, String enc)` Write a `String` to the request body, encoded using the encoding `enc`.
`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.

Methods inherited from interface io.vertx.core.streams.WriteStream
writeQueueFull

- Method Detail
  - exceptionHandler
```
HttpClientRequest exceptionHandler(Handler<Throwable> handler)
```
    Description copied from interface: WriteStream
    
    Set an exception handler on the write stream.
    
    Specified by:
    
    exceptionHandler in interface ReadStream<HttpClientResponse>
    
    Specified by:
    
    exceptionHandler in interface StreamBase
    
    Specified by:
    
    exceptionHandler in interface WriteStream<Buffer>
    
    Parameters:
    
    handler - the exception handler
    
    Returns:
    
    a reference to this, so the API can be used fluently
  - write
```
HttpClientRequest write(Buffer data)
```
    Description copied from interface: WriteStream
    
    Write 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.
    
    Specified by:
    
    write in interface WriteStream<Buffer>
    
    Parameters:
    
    data - the data to write
    
    Returns:
    
    a reference to this, so the API can be used fluently
    
    Throws:
    
    IllegalStateException - when no response handler is set
  - setWriteQueueMaxSize
```
HttpClientRequest setWriteQueueMaxSize(int maxSize)
```
    Description copied from interface: WriteStream
    
    Set 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.
    
    Specified by:
    
    setWriteQueueMaxSize in interface WriteStream<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: WriteStream
    
    Set 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.
    
    Specified by:
    
    drainHandler in interface WriteStream<Buffer>
    
    Parameters:
    
    handler - the handler
    
    Returns:
    
    a reference to this, so the API can be used fluently
  - handler
```
HttpClientRequest handler(Handler<HttpClientResponse> handler)
```
    Description copied from interface: ReadStream
    
    Set a data handler. As data is read, the handler will be called with the data.
    
    Specified by:
    
    handler in interface ReadStream<HttpClientResponse>
    
    Returns:
    
    a reference to this, so the API can be used fluently
  - pause
```
HttpClientRequest pause()
```
    Description copied from interface: ReadStream
    
    Pause the ReadSupport. While it's paused, no data will be sent to the dataHandler
    
    Specified by:
    
    pause in interface ReadStream<HttpClientResponse>
    
    Returns:
    
    a reference to this, so the API can be used fluently
  - resume
```
HttpClientRequest resume()
```
    Description copied from interface: ReadStream
    
    Resume reading. If the ReadSupport has been paused, reading will recommence on it.
    
    Specified by:
    
    resume in interface ReadStream<HttpClientResponse>
    
    Returns:
    
    a reference to this, so the API can be used fluently
  - endHandler
```
HttpClientRequest endHandler(Handler<Void> endHandler)
```
    Description copied from interface: ReadStream
    
    Set an end handler. Once the stream has ended, and there is no more data to be read, this handler will be called.
    
    Specified by:
    
    endHandler in interface ReadStream<HttpClientResponse>
    
    Returns:
    
    a reference to this, so the API can be used fluently
  - 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?
  - method
```
HttpMethod method()
```
    The HTTP method for the request.
  - getRawMethod
```
String getRawMethod()
```
    Returns:
    
    the raw value of the method this request sends
  - setRawMethod
```
HttpClientRequest setRawMethod(String method)
```
    Set the value the method to send when the method HttpMethod.OTHER is used.
    
    Parameters:
    
    method - the raw method
    
    Returns:
    
    a reference to this, so the API can be used fluently
  - uri
```
String uri()
```
    Returns:
    
    The URI of the request.
  - 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
  - setHost
```
HttpClientRequest setHost(String host)
```
    Set the request host.
    For HTTP2 it sets the :authority pseudo header otherwise it sets the Host header
  - getHost
```
String getHost()
```
    Returns:
    
    the request host. For HTTP2 it returns the :authority pseudo header otherwise it returns the Host header
  - headers
```
MultiMap headers()
```
    Returns:
    
    The HTTP headers
  - putHeader
```
HttpClientRequest putHeader(String name,
                            String value)
```
    Put an HTTP header
    
    Parameters:
    
    name - The header name
    
    value - The header value
    
    Returns:
    
    a reference to this, so the API can be used fluently
  - putHeader
```
HttpClientRequest putHeader(CharSequence name,
                            CharSequence value)
```
    Like putHeader(String, String) but using CharSequence
  - putHeader
```
HttpClientRequest putHeader(String name,
                            Iterable<String> values)
```
    Put an HTTP header with multiple values
    
    Parameters:
    
    name - The header name
    
    values - The header values
    
    Returns:
    
    @return a reference to this, so the API can be used fluently
  - putHeader
```
HttpClientRequest putHeader(CharSequence name,
                            Iterable<CharSequence> values)
```
    Like putHeader(String, Iterable) but using CharSequence
  - write
```
HttpClientRequest write(String chunk)
```
    Write a String to the request body, encoded as UTF-8.
    
    Returns:
    
    @return a reference to this, so the API can be used fluently
    
    Throws:
    
    IllegalStateException - when no response handler is set
  - write
```
HttpClientRequest write(String chunk,
                        String enc)
```
    Write a String to the request body, encoded using the encoding enc.
    
    Returns:
    
    @return a reference to this, so the API can be used fluently
    
    Throws:
    
    IllegalStateException - when no response handler is set
  - continueHandler
```
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.
    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
  - sendHead
```
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.
    
    Returns:
    
    a reference to this, so the API can be used fluently
    
    Throws:
    
    IllegalStateException - when no response handler is set
  - sendHead
```
HttpClientRequest sendHead(Handler<HttpVersion> completionHandler)
```
    Like 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.
  - end
```
void end(String chunk)
```
    Same as end(Buffer) but writes a String in UTF-8 encoding
    
    Throws:
    
    IllegalStateException - when no response handler is set
  - end
```
void end(String chunk,
         String enc)
```
    Same as end(Buffer) but writes a String with the specified encoding
    
    Throws:
    
    IllegalStateException - when no response handler is set
  - end
```
void 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
    
    Specified by:
    
    end in interface WriteStream<Buffer>
    
    Throws:
    
    IllegalStateException - when no response handler is set
  - end
```
void 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.
    Once the request has ended, it cannot be used any more,
    
    Specified by:
    
    end in interface WriteStream<Buffer>
    
    Throws:
    
    IllegalStateException - when no response handler is set
  - setTimeout
```
HttpClientRequest setTimeout(long timeoutMs)
```
    Set's the amount of time after which if the request does not return any data within the timeout period an TimeoutException will be passed to the exception handler (if provided) and the request will be closed.
    Calling this method more than once has the effect of canceling any existing timeout and starting the timeout from scratch.
    
    Parameters:
    
    timeoutMs - The quantity 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-only HttpClientRequest, the following methods can be called:
    In addition the handler should call the handler(io.vertx.core.Handler<io.vertx.core.http.HttpClientResponse>) 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 void reset()
```
    Reset this stream with the error code 0.
  - reset
```
void reset(long code)
```
    Reset this stream with the error code.
    
    Parameters:
    
    code - the error code
  - connection
```
HttpConnection connection()
```
    Returns:
    
    the HttpConnection associated with this request
  - connectionHandler
```
HttpClientRequest connectionHandler(Handler<HttpConnection> handler)
```
    Set a connection handler called when an HTTP connection has been established.
    
    Parameters:
    
    handler - the handler
    
    Returns:
    
    a reference to this, so the API can be used fluently
  - writeCustomFrame
```
HttpClientRequest 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(Handler) should be used for this purpose.
    
    Parameters:
    
    type - the 8-bit frame type
    
    flags - the 8-bit frame flags
    
    payload - 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 HttpClientRequest writeCustomFrame(HttpFrame frame)
```
    Like writeCustomFrame(int, int, Buffer) but with an HttpFrame.
    
    Parameters:
    
    frame - the frame to write

Interface HttpClientRequest

Method Summary

Methods inherited from interface io.vertx.core.streams.WriteStream

Method Detail

exceptionHandler

write

setWriteQueueMaxSize

drainHandler

handler

pause

resume

endHandler

setChunked

isChunked

method

getRawMethod

setRawMethod

uri

path

query

setHost

getHost

headers

putHeader

putHeader

putHeader

putHeader

write

write

continueHandler

sendHead

sendHead

end

end

end

end

setTimeout

pushHandler

reset

reset

connection

connectionHandler

writeCustomFrame

streamId

writeCustomFrame