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(Handler)`
  - `sendStream(ReadStream, Handler)`
  - `sendJson(Object, Handler)` ()}
  - `sendForm(MultiMap, Handler)`
  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 and 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
    `default HttpRequest<T>` | `expect(java.util.function.Function<HttpResponse<Void>,ResponsePredicateResult> predicate)` Add an expectation that the response is valid according to the provided `predicate`.
    `HttpRequest<T>` | `expect(ResponsePredicate predicate)` Add an expectation that the response is valid according to the provided `predicate`.
    `List<ResponsePredicate>` | `expectations()`
    `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.
    `default Future<HttpResponse<T>>` | `send()`
    `void` | `send(Handler<AsyncResult<HttpResponse<T>>> handler)` Send a request, the `handler` will receive the response as an `HttpResponse`.
    `default Future<HttpResponse<T>>` | `sendBuffer(Buffer body)`
    `void` | `sendBuffer(Buffer body, Handler<AsyncResult<HttpResponse<T>>> handler)` Like `send(Handler)` but with an HTTP request `body` buffer.
    `default Future<HttpResponse<T>>` | `sendForm(MultiMap body)`
    `void` | `sendForm(MultiMap body, Handler<AsyncResult<HttpResponse<T>>> handler)` Like `send(Handler)` but with an HTTP request `body` multimap encoded as form and the content type set to `application/x-www-form-urlencoded`.
    `default Future<HttpResponse<T>>` | `sendForm(MultiMap body, String charset)`
    `void` | `sendForm(MultiMap body, String charset, Handler<AsyncResult<HttpResponse<T>>> handler)` Like `send(Handler)` but with an HTTP request `body` multimap encoded as form and the content type set to `application/x-www-form-urlencoded`.
    `default Future<HttpResponse<T>>` | `sendJson(Object body)`
    `void` | `sendJson(Object body, Handler<AsyncResult<HttpResponse<T>>> handler)` Like `send(Handler)` but with an HTTP request `body` object encoded as json and the content type set to `application/json`.
    `default Future<HttpResponse<T>>` | `sendJsonObject(JsonObject body)`
    `void` | `sendJsonObject(JsonObject body, Handler<AsyncResult<HttpResponse<T>>> handler)` Like `send(Handler)` but with an HTTP request `body` object encoded as json and the content type set to `application/json`.
    `default Future<HttpResponse<T>>` | `sendMultipartForm(MultipartForm body)`
    `void` | `sendMultipartForm(MultipartForm body, Handler<AsyncResult<HttpResponse<T>>> handler)` Like `send(Handler)` but with an HTTP request `body` multimap encoded as form and the content type set to `multipart/form-data`.
    `default Future<HttpResponse<T>>` | `sendStream(ReadStream<Buffer> body)`
    `void` | `sendStream(ReadStream<Buffer> body, Handler<AsyncResult<HttpResponse<T>>> handler)` Like `send(Handler)` 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, 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`.
    `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`.
    `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)` Sets both connect and idle timeouts for the request connect timeout: if the request is not obtained from the client within the timeout period, the `Future<HttpClientRequest>` obtained from the client is failed with a `TimeoutException`. idle timeout: 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`, e.g.
    `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

    - #### 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)

      Sets both connect and idle timeouts for the request
      - connect timeout: if the request is not obtained from the client within the timeout period, the `Future<HttpClientRequest>` obtained from the client is failed with a `TimeoutException`.
      - idle timeout: 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`, e.g. `Future<HttpClientResponse>` or `Future<Buffer>` response body.
      The connect and idle timeouts can be set separately using `connectTimeout(long)` and `idleTimeout(long)`

    - #### 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 in milliseconds

    - #### 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 in milliseconds

    - #### 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

    - #### 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

    - #### expect

          default HttpRequest<T> expect(java.util.function.Function<HttpResponse<Void>,ResponsePredicateResult> predicate)

      Add an expectation that the response is valid according to the provided `predicate`.

      Multiple predicates can be added.

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

    - #### expect

          HttpRequest<T> expect(ResponsePredicate predicate)

      Add an expectation that the response is valid according to the provided `predicate`.

      Multiple predicates can be added.

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

    - #### expectations

          List<ResponsePredicate> expectations()

      Returns:
        a read-only list of the response predicate expectations

    - #### 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

          void sendStream(ReadStream<Buffer> body,
                          Handler<AsyncResult<HttpResponse<T>>> handler)

      Like `send(Handler)` but with an HTTP request `body` stream.
      Parameters:
        `body` - the body

    - #### sendStream

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

      Parameters:
        `body` - the body
      See Also:
        `sendStream(ReadStream, Handler)`

    - #### sendBuffer

          void sendBuffer(Buffer body,
                          Handler<AsyncResult<HttpResponse<T>>> handler)

      Like `send(Handler)` but with an HTTP request `body` buffer.
      Parameters:
        `body` - the body

    - #### sendBuffer

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

      Parameters:
        `body` - the body
      See Also:
        `sendBuffer(Buffer, Handler)`

    - #### sendJsonObject

          void sendJsonObject(JsonObject body,
                              Handler<AsyncResult<HttpResponse<T>>> handler)

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

    - #### sendJsonObject

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

      Parameters:
        `body` - the body
      See Also:
        `sendJsonObject(JsonObject, Handler)`

    - #### sendJson

          void sendJson(Object body,
                        Handler<AsyncResult<HttpResponse<T>>> handler)

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

    - #### sendJson

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

      Parameters:
        `body` - the body
      See Also:
        `sendJson(Object, Handler)`

    - #### sendForm

          void sendForm(MultiMap body,
                        Handler<AsyncResult<HttpResponse<T>>> handler)

      Like `send(Handler)` 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

    - #### sendForm

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

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

    - #### sendForm

          void sendForm(MultiMap body,
                        String charset,
                        Handler<AsyncResult<HttpResponse<T>>> handler)

      Like `send(Handler)` 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

    - #### sendForm

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

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

    - #### sendMultipartForm

          void sendMultipartForm(MultipartForm body,
                                 Handler<AsyncResult<HttpResponse<T>>> handler)

      Like `send(Handler)` 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

    - #### sendMultipartForm

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

      Parameters:
        `body` - the body
      See Also:
        `sendMultipartForm(MultipartForm, Handler)`

    - #### send

          void send(Handler<AsyncResult<HttpResponse<T>>> handler)

      Send a request, the `handler` will receive the response as an `HttpResponse`.

    - #### send

          default Future<HttpResponse<T>> send()

      See Also:
        `send(Handler)`

Copyright © 2023 Eclipse. All rights reserved.