Package io.vertx.ext.web.client

## Interface HttpRequest<T>

- Type Parameters:
    `T` - the type of response body

      public interface HttpRequest<T>

  A client-side HTTP request.

  Instances are created by an `WebClient` instance, via one of the methods corresponding to the specific HTTP methods such as `WebClient.get(java.lang.String)`, etc...

  The request shall be configured prior sending, the request is immutable and when a mutator method is called, a new request is returned allowing to expose the request in a public API and apply further customization.

  After the request has been configured, the methods

  - `send()`
  - `sendStream(ReadStream)`
  - `sendJson(Object)` ()}
  - `sendForm(MultiMap)`
  can be called. The `sendXXX` methods perform the actual request, they can be called multiple times to perform the same HTTP request at different points in time.

  The handler is called back with

  - an `HttpResponse` instance when the HTTP response has been received
  - a failure when the HTTP request failed (like a connection error) or when the HTTP response could not be obtained (like connection or unmarshalling errors)

  Most of the time, this client will buffer the HTTP response fully unless a specific `BodyCodec` is used such as `BodyCodec#create(Handler)`.

  Author:
    Julien Viet

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `HttpRequest<T>` | `addQueryParam​(String paramName, String paramValue)` | Add a query parameter to the request.
    `<U> HttpRequest<U>` | `as​(BodyCodec<U> responseCodec)` | Configure the request to decode the response with the `responseCodec`.
    `HttpRequest<T>` | `authentication​(Credentials credentials)` | Configure the request to perform HTTP Authentication.
    `default HttpRequest<T>` | `basicAuthentication​(Buffer id, Buffer password)` | Configure the request to perform basic access authentication.
    `default HttpRequest<T>` | `basicAuthentication​(String id, String password)` | Configure the request to perform basic access authentication.
    `default HttpRequest<T>` | `bearerTokenAuthentication​(String bearerToken)` | Configure the request to perform bearer token authentication.
    `BodyCodec<T>` | `bodyCodec()` |
    `long` | `connectTimeout()` |
    `HttpRequest<T>` | `connectTimeout​(long timeout)` | Sets the amount of time after which, if the request is not obtained from the client within the timeout period, the response is failed with a `TimeoutException`.
    `HttpRequest<T>` | `copy()` | Copy this request
    `boolean` | `followRedirects()` |
    `HttpRequest<T>` | `followRedirects​(boolean value)` | Set whether to follow request redirections
    `MultiMap` | `headers()` |
    `String` | `host()` |
    `HttpRequest<T>` | `host​(String value)` | Configure the request to use a new host `value`.
    `long` | `idleTimeout()` |
    `HttpRequest<T>` | `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`.
    `HttpMethod` | `method()` |
    `HttpRequest<T>` | `method​(HttpMethod value)` | Configure the request to use a new method `value`.
    `boolean` | `multipartMixed()` |
    `HttpRequest<T>` | `multipartMixed​(boolean allow)` | Allow or disallow multipart mixed encoding when sending `MultipartForm` having files sharing the same file name.
    `int` | `port()` |
    `HttpRequest<T>` | `port​(int value)` | Configure the request to use a new port `value`.
    `ProxyOptions` | `proxy()` |
    `HttpRequest<T>` | `proxy​(ProxyOptions proxyOptions)` | Configure the request to set a proxy for this request.
    `HttpRequest<T>` | `putHeader​(String name, Iterable<String> value)` | Configure the request to set a new HTTP header with multiple values.
    `HttpRequest<T>` | `putHeader​(String name, String value)` | Configure the request to set a new HTTP header.
    `HttpRequest<T>` | `putHeaders​(MultiMap headers)` | Configure the request to add multiple HTTP headers .
    `MultiMap` | `queryParams()` | Return the current query parameters.
    `String` | `routingKey()` | Return the routing key, the routing key can be used by a Vert.x client side sticky load balancer to pin the request to a remote HTTP server.
    `HttpRequest<T>` | `routingKey​(String key)` | Set the routing key, the routing key can be used by a Vert.x client side sticky load balancer to pin the request to a remote HTTP server.
    `Future<HttpResponse<T>>` | `send()` | Send a request, the `handler` will receive the response as an `HttpResponse`.
    `Future<HttpResponse<T>>` | `sendBuffer​(Buffer body)` | Like `send()` but with an HTTP request `body` buffer.
    `Future<HttpResponse<T>>` | `sendForm​(MultiMap body)` | Like `send()` but with an HTTP request `body` multimap encoded as form and the content type set to `application/x-www-form-urlencoded`.
    `Future<HttpResponse<T>>` | `sendForm​(MultiMap body, String charset)` | Like `send()` but with an HTTP request `body` multimap encoded as form and the content type set to `application/x-www-form-urlencoded`.
    `Future<HttpResponse<T>>` | `sendJson​(Object body)` | Like `send()` but with an HTTP request `body` object encoded as json and the content type set to `application/json`.
    `Future<HttpResponse<T>>` | `sendJsonObject​(JsonObject body)` | Like `send()` but with an HTTP request `body` object encoded as json and the content type set to `application/json`.
    `Future<HttpResponse<T>>` | `sendMultipartForm​(MultipartForm body)` | Like `send()` but with an HTTP request `body` multimap encoded as form and the content type set to `multipart/form-data`.
    `Future<HttpResponse<T>>` | `sendStream​(ReadStream<Buffer> body)` | Like `send()` but with an HTTP request `body` stream.
    `HttpRequest<T>` | `setQueryParam​(String paramName, String paramValue)` | Set a query parameter to the request.
    `HttpRequest<T>` | `setTemplateParam​(String paramName, String paramValue)` | Set a request URI template string parameter to the request, expanded when the request URI is a `UriTemplate`.
    `HttpRequest<T>` | `setTemplateParam​(String paramName, List<String> paramValue)` | Set a request URI template list parameter to the request, expanded when the request URI is a `UriTemplate`.
    `HttpRequest<T>` | `setTemplateParam​(String paramName, Map<String,​String> paramValue)` | Set a request URI template map parameter to the request, expanded when the request URI is a `UriTemplate`.
    `Boolean` | `ssl()` |
    `HttpRequest<T>` | `ssl​(Boolean value)` | Configure the request whether to use SSL.
    `Variables` | `templateParams()` | Return the current request URI template parameters.
    `long` | `timeout()` |
    `HttpRequest<T>` | `timeout​(long value)` | Configures the amount of time in milliseconds after which if the request does not return any data within the timeout period an `TimeoutException` fails the request.
    `String` | `traceOperation()` |
    `HttpRequest<T>` | `traceOperation​(String traceOperation)` | Trace operation name override.
    `String` | `uri()` |
    `HttpRequest<T>` | `uri​(String value)` | Configure the request to use a new request URI `value`.
    `String` | `virtualHost()` |
    `HttpRequest<T>` | `virtualHost​(String value)` | Configure the request to use a virtual host `value`.

- - ### Method Detail

    - #### method

          HttpRequest<T> method​(HttpMethod value)

      Configure the request to use a new method `value`.
      Returns:
        a reference to this, so the API can be used fluently

    - #### method

          HttpMethod method()

      Returns:
        the request method

    - #### port

          HttpRequest<T> port​(int value)

      Configure the request to use a new port `value`.

      This overrides the port set by absolute URI requests

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

    - #### port

          int port()

      Returns:
        the request port or `0` when none is set for absolute URI templates

    - #### as

          <U> HttpRequest<U> as​(BodyCodec<U> responseCodec)

      Configure the request to decode the response with the `responseCodec`.
      Parameters:
        `responseCodec` - the response codec
      Returns:
        a reference to this, so the API can be used fluently

    - #### bodyCodec

          BodyCodec<T> bodyCodec()

      Returns:
        the request body codec

    - #### host

          HttpRequest<T> host​(String value)

      Configure the request to use a new host `value`.

      This overrides the host set by absolute URI requests

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

    - #### host

          String host()

      Returns:
        the request host or `null` when none is set for absolute URI templates

    - #### virtualHost

          HttpRequest<T> virtualHost​(String value)

      Configure the request to use a virtual host `value`.

      Usually the header host (:authority pseudo header for HTTP/2) is set from the request host value since this host value resolves to the server IP address.

      Sometimes you need to set a host header for an address that does not resolve to the server IP address. The virtual host value overrides the value of the actual host header (:authority pseudo header for HTTP/2).

      The virtual host is also be used for SNI.
      Returns:
        a reference to this, so the API can be used fluently

    - #### virtualHost

          String virtualHost()

      Returns:
        the request virtual host if any or `null`

    - #### uri

          HttpRequest<T> uri​(String value)

      Configure the request to use a new request URI `value`.

      This overrides the port set by absolute URI requests

      When the uri has query parameters, they are set in the `queryParams()`, overwriting any parameters previously set

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

    - #### uri

          String uri()

      Returns:
        the request uri or `null` when none is set for absolute URI templates, when the request uri is a template, the template is extrapolated tolerating missing variables.

    - #### putHeaders

          HttpRequest<T> putHeaders​(MultiMap headers)

      Configure the request to add multiple HTTP headers .
      Parameters:
        `headers` - The HTTP headers
      Returns:
        a reference to this, so the API can be used fluently

    - #### putHeader

          HttpRequest<T> putHeader​(String name,
                                   String value)

      Configure the request to set a new HTTP header.
      Parameters:
        `name` - the header name
        `value` - the header value
      Returns:
        a reference to this, so the API can be used fluently

    - #### putHeader

          HttpRequest<T> putHeader​(String name,
                                   Iterable<String> value)

      Configure the request to set a new HTTP header with multiple values.
      Parameters:
        `name` - the header name
        `value` - the header value
      Returns:
        a reference to this, so the API can be used fluently

    - #### headers

          MultiMap headers()

      Returns:
        The HTTP headers

    - #### authentication

          HttpRequest<T> authentication​(Credentials credentials)

      Configure the request to perform HTTP Authentication.

      Performs a generic authentication using the credentials provided by the user. For the sake of validation safety it is recommended that `Credentials.applyHttpChallenge(String)` is called to ensure that the credentials are applicable to the HTTP Challenged received on a previous request that returned a 401 response code.

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

    - #### basicAuthentication

          default HttpRequest<T> basicAuthentication​(String id,
                                                     String password)

      Configure the request to perform basic access authentication.

      In basic HTTP authentication, a request contains a header field of the form 'Authorization: Basic <credentials>', where credentials is the base64 encoding of id and password joined by a colon.

      In practical terms the arguments are converted to a `UsernamePasswordCredentials` object.
      Parameters:
        `id` - the id
        `password` - the password
      Returns:
        a reference to this, so the API can be used fluently

    - #### basicAuthentication

          default HttpRequest<T> basicAuthentication​(Buffer id,
                                                     Buffer password)

      Configure the request to perform basic access authentication.

      In basic HTTP authentication, a request contains a header field of the form 'Authorization: Basic <credentials>', where credentials is the base64 encoding of id and password joined by a colon.

      In practical terms the arguments are converted to a `UsernamePasswordCredentials` object.
      Parameters:
        `id` - the id
        `password` - the password
      Returns:
        a reference to this, so the API can be used fluently

    - #### bearerTokenAuthentication

          default HttpRequest<T> bearerTokenAuthentication​(String bearerToken)

      Configure the request to perform bearer token authentication.

      In OAuth 2.0, a request contains a header field of the form 'Authorization: Bearer <bearerToken>', where bearerToken is the bearer token issued by an authorization server to access protected resources.

      In practical terms the arguments are converted to a `TokenCredentials` object.
      Parameters:
        `bearerToken` - the bearer token
      Returns:
        a reference to this, so the API can be used fluently

    - #### ssl

          HttpRequest<T> ssl​(Boolean value)

      Configure the request whether to use SSL.

      This overrides the SSL value set by absolute URI requests

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

    - #### ssl

          Boolean ssl()

      Returns:
        whether the request uses SSL or `null` when none is set for absolute URI templates

    - #### timeout

          HttpRequest<T> timeout​(long value)

      Configures the amount of time in milliseconds after which if the request does not return any data within the timeout period an `TimeoutException` fails the request.

      Setting zero or a negative `value` disables the timeout.

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

    - #### timeout

          long timeout()

      Returns:
        the current timeout in milliseconds

    - #### idleTimeout

          HttpRequest<T> 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`.

      The timeout starts after a connection is obtained from the client.
      Parameters:
        `timeout` - the amount of time in milliseconds.
      Returns:
        a reference to this, so the API can be used fluently

    - #### idleTimeout

          long idleTimeout()

      Returns:
        the idle timeout

    - #### connectTimeout

          HttpRequest<T> connectTimeout​(long timeout)

      Sets the amount of time after which, if the request is not obtained from the client within the timeout period, the response is failed with a `TimeoutException`. Note this is not related to the TCP `HttpClientOptions.setConnectTimeout(int)` option, when a request is made against a pooled HTTP client, the timeout applies to the duration to obtain a connection from the pool to serve the request, the timeout might fire because the server does not respond in time or the pool is too busy to serve a request.
      Parameters:
        `timeout` - the amount of time in milliseconds.
      Returns:
        a reference to this, so the API can be used fluently

    - #### connectTimeout

          long connectTimeout()

      Returns:
        the connect timeout

    - #### addQueryParam

          HttpRequest<T> addQueryParam​(String paramName,
                                       String paramValue)

      Add a query parameter to the request.
      Parameters:
        `paramName` - the param name
        `paramValue` - the param value
      Returns:
        a reference to this, so the API can be used fluently

    - #### setQueryParam

          HttpRequest<T> setQueryParam​(String paramName,
                                       String paramValue)

      Set a query parameter to the request.
      Parameters:
        `paramName` - the param name
        `paramValue` - the param value
      Returns:
        a reference to this, so the API can be used fluently

    - #### setTemplateParam

          HttpRequest<T> setTemplateParam​(String paramName,
                                          String paramValue)

      Set a request URI template string parameter to the request, expanded when the request URI is a `UriTemplate`.
      Parameters:
        `paramName` - the param name
        `paramValue` - the param value
      Returns:
        a reference to this, so the API can be used fluently

    - #### setTemplateParam

          HttpRequest<T> setTemplateParam​(String paramName,
                                          List<String> paramValue)

      Set a request URI template list parameter to the request, expanded when the request URI is a `UriTemplate`.
      Parameters:
        `paramName` - the param name
        `paramValue` - the param value
      Returns:
        a reference to this, so the API can be used fluently

    - #### setTemplateParam

          HttpRequest<T> setTemplateParam​(String paramName,
                                          Map<String,​String> paramValue)

      Set a request URI template map parameter to the request, expanded when the request URI is a `UriTemplate`.
      Parameters:
        `paramName` - the param name
        `paramValue` - the param value
      Returns:
        a reference to this, so the API can be used fluently

    - #### followRedirects

          HttpRequest<T> followRedirects​(boolean value)

      Set whether to follow request redirections
      Parameters:
        `value` - true if redirections should be followed
      Returns:
        a reference to this, so the API can be used fluently

    - #### followRedirects

          boolean followRedirects()

      Returns:
        whether to follow request redirections

    - #### routingKey

          HttpRequest<T> routingKey​(String key)

      Set the routing key, the routing key can be used by a Vert.x client side sticky load balancer to pin the request to a remote HTTP server.
      Parameters:
        `key` - the routing key
      Returns:
        a reference to this, so the API can be used fluently

    - #### routingKey

          String routingKey()

      Return the routing key, the routing key can be used by a Vert.x client side sticky load balancer to pin the request to a remote HTTP server.
      Returns:
        the routing key

    - #### proxy

          HttpRequest<T> proxy​(ProxyOptions proxyOptions)

      Configure the request to set a proxy for this request. Setting proxy here supersedes the proxy set on the client itself
      Parameters:
        `proxyOptions` - The proxy options
      Returns:
        a reference to this, so the API can be used fluently

    - #### proxy

          ProxyOptions proxy()

      Returns:
        the proxy for this request

    - #### queryParams

          MultiMap queryParams()

      Return the current query parameters.
      Returns:
        the current query parameters

    - #### templateParams

          Variables templateParams()

      Return the current request URI template parameters.
      Returns:
        the current request URI template parameters

    - #### copy

          HttpRequest<T> copy()

      Copy this request
      Returns:
        a copy of this request

    - #### multipartMixed

          HttpRequest<T> multipartMixed​(boolean allow)

      Allow or disallow multipart mixed encoding when sending `MultipartForm` having files sharing the same file name.
      The default value is `true`.
      Set to `false` if you want to achieve the behavior for HTML5.
      Parameters:
        `allow` - `true` allows use of multipart mixed encoding
      Returns:
        a reference to this, so the API can be used fluently

    - #### multipartMixed

          boolean multipartMixed()

      Returns:
        whether multipart mixed encoding is allowed

    - #### traceOperation

          HttpRequest<T> traceOperation​(String traceOperation)

      Trace operation name override.
      Parameters:
        `traceOperation` - Name of operation to use in traces
      Returns:
        a reference to this, so the API can be used fluently

    - #### traceOperation

          String traceOperation()

      Returns:
        the trace operation name override

    - #### sendStream

          Future<HttpResponse<T>> sendStream​(ReadStream<Buffer> body)

      Like `send()` but with an HTTP request `body` stream.
      Parameters:
        `body` - the body
      See Also:
        `sendStream(ReadStream)`

    - #### sendBuffer

          Future<HttpResponse<T>> sendBuffer​(Buffer body)

      Like `send()` but with an HTTP request `body` buffer.
      Parameters:
        `body` - the body
      See Also:
        `sendBuffer(Buffer)`

    - #### sendJsonObject

          Future<HttpResponse<T>> sendJsonObject​(JsonObject body)

      Like `send()` but with an HTTP request `body` object encoded as json and the content type set to `application/json`.
      Parameters:
        `body` - the body
      See Also:
        `sendJsonObject(JsonObject)`

    - #### sendJson

          Future<HttpResponse<T>> sendJson​(Object body)

      Like `send()` but with an HTTP request `body` object encoded as json and the content type set to `application/json`.
      Parameters:
        `body` - the body
      See Also:
        `sendJson(Object)`

    - #### sendForm

          Future<HttpResponse<T>> sendForm​(MultiMap body)

      Like `send()` but with an HTTP request `body` multimap encoded as form and the content type set to `application/x-www-form-urlencoded`.

      When the content type header is previously set to `multipart/form-data` it will be used instead.

      Parameters:
        `body` - the body
      See Also:
        `sendForm(MultiMap)`

    - #### sendForm

          Future<HttpResponse<T>> sendForm​(MultiMap body,
                                           String charset)

      Like `send()` but with an HTTP request `body` multimap encoded as form and the content type set to `application/x-www-form-urlencoded`.

      When the content type header is previously set to `multipart/form-data` it will be used instead. NOTE: the use of this method is strongly discouraged to use when the form is a `application/x-www-form-urlencoded` encoded form since the charset to use must be UTF-8.

      Parameters:
        `body` - the body
        `charset` - the charset
      See Also:
        `sendForm(MultiMap, String)`

    - #### sendMultipartForm

          Future<HttpResponse<T>> sendMultipartForm​(MultipartForm body)

      Like `send()` but with an HTTP request `body` multimap encoded as form and the content type set to `multipart/form-data`. You may use this method to send attributes and upload files.
      Parameters:
        `body` - the body
      See Also:
        `sendMultipartForm(MultipartForm)`

    - #### send

          Future<HttpResponse<T>> send()

      Send a request, the `handler` will receive the response as an `HttpResponse`.
      See Also:
        `send()`