Package: io.vertx.groovy.core.http

## [Groovy] Class HttpClientRequest

- io.vertx.groovy.core.http.HttpClientRequest

- All Implemented Interfaces and Traits:
    ReadStream, WriteStream

      @groovy.transform.CompileStatic
      class HttpClientRequest
      extends java.lang.Object

  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 HttpClientRequest.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 HttpClientRequest.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:

- - ### Constructor Summary

    Constructors
    Constructor and description
    `HttpClientRequest (java.lang.Object delegate)`

  - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `HttpConnection` | `connection()` @return Returns: the HttpConnection associated with this request
    `HttpClientRequest` | `connectionHandler(io.vertx.core.Handler<HttpConnection> handler)` Set a connection handler called when an HTTP connection has been established.
    `HttpClientRequest` | `continueHandler(io.vertx.core.Handler<java.lang.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(io.vertx.core.Handler<java.lang.Void> handler)`
    `void` | `end(java.lang.String chunk)` Same as HttpClientRequest.end but writes a String in UTF-8 encoding
    `void` | `end(java.lang.String chunk, java.lang.String enc)` Same as HttpClientRequest.end but writes a String with the specified encoding
    `void` | `end(Buffer chunk)` Same as HttpClientRequest.end but writes some data to the request body before ending.
    `void` | `end()` Ends the request.
    `HttpClientRequest` | `endHandler(io.vertx.core.Handler<java.lang.Void> endHandler)`
    `HttpClientRequest` | `exceptionHandler(io.vertx.core.Handler<java.lang.Throwable> handler)`
    `java.lang.Object` | `getDelegate()`
    `java.lang.String` | `getHost()` Returns: the request host.
    `java.lang.String` | `getRawMethod()` @return Returns: the raw value of the method this request sends
    `HttpClientRequest` | `handler(io.vertx.core.Handler<HttpClientResponse> handler)`
    `MultiMap` | `headers()` @return Returns: The HTTP headers
    `boolean` | `isChunked()` Returns: Is the request chunked?
    `io.vertx.core.http.HttpMethod` | `method()` The HTTP method for the request.
    `java.lang.String` | `path()` Returns: The path part of the uri.
    `HttpClientRequest` | `pause()`
    `HttpClientRequest` | `pushHandler(io.vertx.core.Handler<HttpClientRequest> handler)` Set a push handler for this request.
    `HttpClientRequest` | `putHeader(java.lang.String name, java.lang.String value)` Put an HTTP header
    `java.lang.String` | `query()` Returns: the query part of the uri.
    `void` | `reset()` Reset this stream with the error code `0`.
    `void` | `reset(long code)` Reset this stream with the error `code`.
    `HttpClientRequest` | `resume()`
    `HttpClientRequest` | `sendHead()` Forces the head of the request to be written before HttpClientRequest.end is called on the request or any data is written to it.
    `HttpClientRequest` | `sendHead(io.vertx.core.Handler<io.vertx.core.http.HttpVersion> completionHandler)` Like HttpClientRequest.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(java.lang.String host)` Set the request host.
    `HttpClientRequest` | `setRawMethod(java.lang.String method)` Set the value the method to send when the method 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 java.util.concurrent.TimeoutException will be passed to the exception handler (if provided) and the request will be closed.
    `HttpClientRequest` | `setWriteQueueMaxSize(int maxSize)`
    `int` | `streamId()` @return Returns: the id of the stream of this response, when it is not yet determined, i.e the request has not been yet sent or it is not supported HTTP/1.x
    `java.lang.String` | `uri()` Returns: The URI of the request.
    `HttpClientRequest` | `write(Buffer data)` @throws java.lang.IllegalStateException when no response handler is set
    `HttpClientRequest` | `write(java.lang.String chunk)` Write a java.lang.String to the request body, encoded as UTF-8.
    `HttpClientRequest` | `write(java.lang.String chunk, java.lang.String enc)` Write a java.lang.String to the request body, encoded using the encoding `enc`.
    `HttpClientRequest` | `writeCustomFrame(int type, int flags, Buffer payload)` Write an HTTP/2 frame to the request, allowing to extend the HTTP/2 protocol.
    `HttpClientRequest` | `writeCustomFrame(HttpFrame frame)` Like HttpClientRequest.writeCustomFrame but with an HttpFrame.
    `boolean` | `writeQueueFull()` This will return `true` if there are more bytes in the write queue than the value set using HttpClientRequest.setWriteQueueMaxSize

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class java.lang.Object` | `java.lang.Object#wait(long, int), java.lang.Object#wait(long), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll()`

- - ### Constructor Detail

    - #### HttpClientRequest(java.lang.Object delegate)

  - ### Method Detail

    - #### HttpConnection connection()

      Returns:
        the HttpConnection associated with this request

    - #### HttpClientRequest connectionHandler(io.vertx.core.Handler<HttpConnection> handler)

      Set a connection handler called when an HTTP connection has been established.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `handler` - the handler

    - #### HttpClientRequest continueHandler(io.vertx.core.Handler<java.lang.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 HttpClientRequest.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
      Parameters:
        handler

    - #### HttpClientRequest drainHandler(io.vertx.core.Handler<java.lang.Void> handler)

    - #### void end(java.lang.String chunk)

      Same as HttpClientRequest.end but writes a String in UTF-8 encoding

      Parameters:
        chunk

    - #### void end(java.lang.String chunk, java.lang.String enc)

      Same as HttpClientRequest.end but writes a String with the specified encoding

      Parameters:
        chunk
        enc

    - #### void end(Buffer chunk)

      Same as HttpClientRequest.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

      Parameters:
        chunk

    - #### void end()

      Ends the request. If no data has been written to the request body, and HttpClientRequest.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,

    - #### HttpClientRequest endHandler(io.vertx.core.Handler<java.lang.Void> endHandler)

    - #### HttpClientRequest exceptionHandler(io.vertx.core.Handler<java.lang.Throwable> handler)

    - #### java.lang.Object getDelegate()

    - #### java.lang.String getHost()

      Returns:
        the request host. For HTTP2 it returns the pseudo header otherwise it returns the header

    - #### java.lang.String getRawMethod()

      Returns:
        the raw value of the method this request sends

    - #### HttpClientRequest handler(io.vertx.core.Handler<HttpClientResponse> handler)

    - #### MultiMap headers()

      Returns:
        The HTTP headers

    - #### boolean isChunked()

      Returns:
        Is the request chunked?

    - #### io.vertx.core.http.HttpMethod method()

      The HTTP method for the request.

      Returns:

    - #### java.lang.String path()

      Returns:
        The path part of the uri. For example /somepath/somemorepath/someresource.foo

    - #### HttpClientRequest pause()

    - #### HttpClientRequest pushHandler(io.vertx.core.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:

      - HttpClientRequest.method
      - HttpClientRequest.uri
      - HttpClientRequest.headers
      - HttpClientRequest.getHost
      In addition the handler should call the HttpClientRequest.handler method to set an handler to process the response.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `handler` - the handler

    - #### HttpClientRequest putHeader(java.lang.String name, java.lang.String value)

      Put an HTTP header

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `name` - The header name
        `value` - The header value

    - #### java.lang.String query()

      Returns:
        the query part of the uri. For example someparam=32&someotherparam=x

    - #### void reset()

      Reset this stream with the error code `0`.

    - #### void reset(long code)

      Reset this stream with the error `code`.

      Parameters:
        `code` - the error code

    - #### HttpClientRequest resume()

    - #### HttpClientRequest sendHead()

      Forces the head of the request to be written before HttpClientRequest.end is called on the request or any data is written to it.

      This is normally used to implement HTTP 100-continue handling, see for more information.

      Returns:
        a reference to this, so the API can be used fluently

    - #### HttpClientRequest sendHead(io.vertx.core.Handler<io.vertx.core.http.HttpVersion> completionHandler)

      Like HttpClientRequest.sendHead but with an handler after headers have been sent. The handler will be called with the io.vertx.groovy.core.http.HttpVersion if it can be determined or null otherwise.

      Returns:
      Parameters:
        completionHandler

    - #### HttpClientRequest setChunked(boolean chunked)

      If chunked is true then the request will be set into HTTP chunked mode

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `chunked` - true if chunked encoding

    - #### HttpClientRequest setHost(java.lang.String host)

      Set the request host.

      For HTTP2 it sets the pseudo header otherwise it sets the header
      Returns:
      Parameters:
        host

    - #### HttpClientRequest setRawMethod(java.lang.String method)

      Set the value the method to send when the method is used.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `method` - the raw method

    - #### 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 java.util.concurrent.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.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `timeoutMs` - The quantity of time in milliseconds.

    - #### HttpClientRequest setWriteQueueMaxSize(int maxSize)

    - #### int streamId()

      Returns:
        the id of the stream of this response, when it is not yet determined, i.e the request has not been yet sent or it is not supported HTTP/1.x

    - #### java.lang.String uri()

      Returns:
        The URI of the request.

    - #### HttpClientRequest write(Buffer data)

      throws:
        java.lang.IllegalStateException when no response handler is set
      Returns:
      Parameters:
        data

    - #### HttpClientRequest write(java.lang.String chunk)

      Write a java.lang.String to the request body, encoded as UTF-8.

      Returns:
        @return a reference to this, so the API can be used fluently
      Parameters:
        chunk

    - #### HttpClientRequest write(java.lang.String chunk, java.lang.String enc)

      Write a java.lang.String to the request body, encoded using the encoding `enc`.

      Returns:
        @return a reference to this, so the API can be used fluently
      Parameters:
        chunk
        enc

    - #### 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 HttpClientRequest.sendHead should be used for this purpose.

      Returns:
        a reference to this, so the API can be used fluently
      Parameters:
        `type` - the 8-bit frame type
        `flags` - the 8-bit frame flags
        `payload` - the frame payload

    - #### HttpClientRequest writeCustomFrame(HttpFrame frame)

      Like HttpClientRequest.writeCustomFrame but with an HttpFrame.

      Returns:
      Parameters:
        `frame` - the frame to write

    - #### boolean writeQueueFull()

      This will return `true` if there are more bytes in the write queue than the value set using HttpClientRequest.setWriteQueueMaxSize

      Returns:
        true if write queue is full