io.vertx.core.http

## Interface HttpClient

- All Superinterfaces:
    Measured

      public interface HttpClient
      extends Measured

  An asynchronous HTTP client.

  It allows you to make requests to HTTP servers, and a single client can make requests to any server.

  This gives the benefits of keep alive when the client is loaded but means we don't keep connections hanging around unnecessarily when there would be no benefits anyway.

  The client is designed to be reused between requests.

  Author:
    Tim Fox

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Future<Void>` | `close()` Like `close(Handler)` but returns a `Future` of the asynchronous result
    `void` | `close(Handler<AsyncResult<Void>> handler)` Close the client.
    `HttpClient` | `connectionHandler(Handler<HttpConnection> handler)` Deprecated. instead use `HttpClientBuilder.withConnectHandler(Handler)`
    `java.util.function.Function<HttpClientResponse,Future<RequestOptions>>` | `redirectHandler()` Deprecated.
    `HttpClient` | `redirectHandler(java.util.function.Function<HttpClientResponse,Future<RequestOptions>> handler)` Deprecated. instead use `HttpClientBuilder.withRedirectHandler(Function)`
    `default Future<HttpClientRequest>` | `request(HttpMethod method, int port, String host, String requestURI)` Like `request(HttpMethod, int, String, String, Handler)` but returns a `Future` of the asynchronous result
    `void` | `request(HttpMethod method, int port, String host, String requestURI, Handler<AsyncResult<HttpClientRequest>> handler)` Create an HTTP request to send to the server at the `host` and `port`.
    `default Future<HttpClientRequest>` | `request(HttpMethod method, String requestURI)` Like `request(HttpMethod, String, Handler)` but returns a `Future` of the asynchronous result
    `void` | `request(HttpMethod method, String requestURI, Handler<AsyncResult<HttpClientRequest>> handler)` Create an HTTP request to send to the server at the default host and port.
    `default Future<HttpClientRequest>` | `request(HttpMethod method, String host, String requestURI)` Like `request(HttpMethod, String, String, Handler)` but returns a `Future` of the asynchronous result
    `void` | `request(HttpMethod method, String host, String requestURI, Handler<AsyncResult<HttpClientRequest>> handler)` Create an HTTP request to send to the server at the `host` and default port.
    `Future<HttpClientRequest>` | `request(RequestOptions options)` Like `request(RequestOptions, Handler)` but returns a `Future` of the asynchronous result
    `void` | `request(RequestOptions options, Handler<AsyncResult<HttpClientRequest>> handler)` Create an HTTP request to send to the server.
    `default Future<Boolean>` | `updateSSLOptions(SSLOptions options)` Update the client with new SSL `options`, the update happens if the options object is valid and different from the existing options object.
    `Future<Boolean>` | `updateSSLOptions(SSLOptions options, boolean force)` Update the client with new SSL `options`, the update happens if the options object is valid and different from the existing options object.
    `default void` | `updateSSLOptions(SSLOptions options, boolean force, Handler<AsyncResult<Boolean>> handler)` Like `updateSSLOptions(SSLOptions)` but supplying a handler that will be called when the update happened (or has failed).
    `default void` | `updateSSLOptions(SSLOptions options, Handler<AsyncResult<Boolean>> handler)` Like `updateSSLOptions(SSLOptions)` but supplying a handler that will be called when the update happened (or has failed).
    `Future<WebSocket>` | `webSocket(int port, String host, String requestURI)` Deprecated. instead use `WebSocketClient.connect(int, String, String)`
    `void` | `webSocket(int port, String host, String requestURI, Handler<AsyncResult<WebSocket>> handler)` Deprecated. instead use `WebSocketClient.connect(int, String, String, Handler)`
    `Future<WebSocket>` | `webSocket(String requestURI)` Deprecated. instead use `WebSocketClient.connect(int, String, String)`
    `void` | `webSocket(String requestURI, Handler<AsyncResult<WebSocket>> handler)` Deprecated. instead use `WebSocketClient.connect(int, String, String, Handler)`
    `Future<WebSocket>` | `webSocket(String host, String requestURI)` Deprecated. instead use `WebSocketClient.connect(int, String, String)`
    `void` | `webSocket(String host, String requestURI, Handler<AsyncResult<WebSocket>> handler)` Deprecated. instead use `WebSocketClient.connect(int, String, String, Handler)`
    `Future<WebSocket>` | `webSocket(WebSocketConnectOptions options)` Deprecated. instead use `WebSocketClient.connect(WebSocketConnectOptions)`
    `void` | `webSocket(WebSocketConnectOptions options, Handler<AsyncResult<WebSocket>> handler)` Deprecated. instead use `WebSocketClient.connect(WebSocketConnectOptions, Handler)`
    `Future<WebSocket>` | `webSocketAbs(String url, MultiMap headers, WebsocketVersion version, List<String> subProtocols)` Deprecated. instead use `WebSocketClient.connect(WebSocketConnectOptions)`
    `void` | `webSocketAbs(String url, MultiMap headers, WebsocketVersion version, List<String> subProtocols, Handler<AsyncResult<WebSocket>> handler)` Deprecated. instead use `WebSocketClient.connect(WebSocketConnectOptions, Handler)`

    - ### Methods inherited from interface io.vertx.core.metrics.Measured

      `isMetricsEnabled`

- - ### Method Detail

    - #### request

          void request(RequestOptions options,
                       Handler<AsyncResult<HttpClientRequest>> handler)

      Create an HTTP request to send to the server. The `handler` is called when the request is ready to be sent.
      Parameters:
        `options` - the request options
        `handler` - the handler called when the request is ready to be sent

    - #### request

          Future<HttpClientRequest> request(RequestOptions options)

      Like `request(RequestOptions, Handler)` but returns a `Future` of the asynchronous result

    - #### request

          void request(HttpMethod method,
                       int port,
                       String host,
                       String requestURI,
                       Handler<AsyncResult<HttpClientRequest>> handler)

      Create an HTTP request to send to the server at the `host` and `port`. The `handler` is called when the request is ready to be sent.
      Parameters:
        `method` - the HTTP method
        `port` - the port
        `host` - the host
        `requestURI` - the relative URI
        `handler` - the handler called when the request is ready to be sent

    - #### request

          default Future<HttpClientRequest> request(HttpMethod method,
                                                    int port,
                                                    String host,
                                                    String requestURI)

      Like `request(HttpMethod, int, String, String, Handler)` but returns a `Future` of the asynchronous result

    - #### request

          void request(HttpMethod method,
                       String host,
                       String requestURI,
                       Handler<AsyncResult<HttpClientRequest>> handler)

      Create an HTTP request to send to the server at the `host` and default port. The `handler` is called when the request is ready to be sent.
      Parameters:
        `method` - the HTTP method
        `host` - the host
        `requestURI` - the relative URI
        `handler` - the handler called when the request is ready to be sent

    - #### request

          default Future<HttpClientRequest> request(HttpMethod method,
                                                    String host,
                                                    String requestURI)

      Like `request(HttpMethod, String, String, Handler)` but returns a `Future` of the asynchronous result

    - #### request

          void request(HttpMethod method,
                       String requestURI,
                       Handler<AsyncResult<HttpClientRequest>> handler)

      Create an HTTP request to send to the server at the default host and port. The `handler` is called when the request is ready to be sent.
      Parameters:
        `method` - the HTTP method
        `requestURI` - the relative URI
        `handler` - the handler called when the request is ready to be sent

    - #### request

          default Future<HttpClientRequest> request(HttpMethod method,
                                                    String requestURI)

      Like `request(HttpMethod, String, Handler)` but returns a `Future` of the asynchronous result

    - #### webSocket

          @Deprecated
          void webSocket(int port,
                                     String host,
                                     String requestURI,
                                     Handler<AsyncResult<WebSocket>> handler)

      Deprecated. instead use `WebSocketClient.connect(int, String, String, Handler)`
      Connect a WebSocket to the specified port, host and relative request URI
      Parameters:
        `port` - the port
        `host` - the host
        `requestURI` - the relative URI
        `handler` - handler that will be called with the WebSocket when connected

    - #### webSocket

          @Deprecated
          Future<WebSocket> webSocket(int port,
                                                  String host,
                                                  String requestURI)

      Deprecated. instead use `WebSocketClient.connect(int, String, String)`
      Like `webSocket(int, String, String, Handler)` but returns a `Future` of the asynchronous result

    - #### webSocket

          @Deprecated
          void webSocket(String host,
                                     String requestURI,
                                     Handler<AsyncResult<WebSocket>> handler)

      Deprecated. instead use `WebSocketClient.connect(int, String, String, Handler)`
      Connect a WebSocket to the host and relative request URI and default port
      Parameters:
        `host` - the host
        `requestURI` - the relative URI
        `handler` - handler that will be called with the WebSocket when connected

    - #### webSocket

          @Deprecated
          Future<WebSocket> webSocket(String host,
                                                  String requestURI)

      Deprecated. instead use `WebSocketClient.connect(int, String, String)`
      Like `webSocket(String, String, Handler)` but returns a `Future` of the asynchronous result

    - #### webSocket

          @Deprecated
          void webSocket(String requestURI,
                                     Handler<AsyncResult<WebSocket>> handler)

      Deprecated. instead use `WebSocketClient.connect(int, String, String, Handler)`
      Connect a WebSocket at the relative request URI using the default host and port
      Parameters:
        `requestURI` - the relative URI
        `handler` - handler that will be called with the WebSocket when connected

    - #### webSocket

          @Deprecated
          Future<WebSocket> webSocket(String requestURI)

      Deprecated. instead use `WebSocketClient.connect(int, String, String)`
      Like `webSocket(String, Handler)` but returns a `Future` of the asynchronous result

    - #### webSocket

          @Deprecated
          void webSocket(WebSocketConnectOptions options,
                                     Handler<AsyncResult<WebSocket>> handler)

      Deprecated. instead use `WebSocketClient.connect(WebSocketConnectOptions, Handler)`
      Connect a WebSocket with the specified options.
      Parameters:
        `options` - the request options

    - #### webSocket

          @Deprecated
          Future<WebSocket> webSocket(WebSocketConnectOptions options)

      Deprecated. instead use `WebSocketClient.connect(WebSocketConnectOptions)`
      Like `webSocket(WebSocketConnectOptions, Handler)` but returns a `Future` of the asynchronous result

    - #### webSocketAbs

          @Deprecated
          void webSocketAbs(String url,
                                        MultiMap headers,
                                        WebsocketVersion version,
                                        List<String> subProtocols,
                                        Handler<AsyncResult<WebSocket>> handler)

      Deprecated. instead use `WebSocketClient.connect(WebSocketConnectOptions, Handler)`
      Connect a WebSocket with the specified absolute url, with the specified headers, using the specified version of WebSockets, and the specified WebSocket sub protocols.
      Parameters:
        `url` - the absolute url
        `headers` - the headers
        `version` - the WebSocket version
        `subProtocols` - the subprotocols to use
        `handler` - handler that will be called if WebSocket connection fails

    - #### webSocketAbs

          @Deprecated
          Future<WebSocket> webSocketAbs(String url,
                                                     MultiMap headers,
                                                     WebsocketVersion version,
                                                     List<String> subProtocols)

      Deprecated. instead use `WebSocketClient.connect(WebSocketConnectOptions)`
      Like `webSocketAbs(String, MultiMap, WebsocketVersion, List, Handler)` but returns a `Future` of the asynchronous result

    - #### updateSSLOptions

          default Future<Boolean> updateSSLOptions(SSLOptions options)

      Update the client with new SSL `options`, the update happens if the options object is valid and different from the existing options object.

      The boolean succeeded future result indicates whether the update occurred.

      Parameters:
        `options` - the new SSL options
      Returns:
        a future signaling the update success

    - #### updateSSLOptions

          default void updateSSLOptions(SSLOptions options,
                                        Handler<AsyncResult<Boolean>> handler)

      Like `updateSSLOptions(SSLOptions)` but supplying a handler that will be called when the update happened (or has failed).
      Parameters:
        `options` - the new SSL options
        `handler` - the update handler

    - #### updateSSLOptions

          Future<Boolean> updateSSLOptions(SSLOptions options,
                                           boolean force)

      Update the client with new SSL `options`, the update happens if the options object is valid and different from the existing options object.

      The `options` object is compared using its `equals` method against the existing options to prevent an update when the objects are equals since loading options can be costly, this can happen for share TCP servers. When object are equals, setting `force` to `true` forces the update.

      The boolean succeeded future result indicates whether the update occurred.

      Parameters:
        `options` - the new SSL options
        `force` - force the update when options are equals
      Returns:
        a future signaling the update success

    - #### updateSSLOptions

          default void updateSSLOptions(SSLOptions options,
                                        boolean force,
                                        Handler<AsyncResult<Boolean>> handler)

      Like `updateSSLOptions(SSLOptions)` but supplying a handler that will be called when the update happened (or has failed).
      Parameters:
        `options` - the new SSL options
        `force` - force the update when options are equals
        `handler` - the update handler

    - #### connectionHandler

          @Deprecated
          HttpClient connectionHandler(Handler<HttpConnection> handler)

      Deprecated. instead use `HttpClientBuilder.withConnectHandler(Handler)`
      Set a connection handler for the client. This handler is called when a new connection is established.
      Returns:
        a reference to this, so the API can be used fluently

    - #### redirectHandler

          @Deprecated
          HttpClient redirectHandler(java.util.function.Function<HttpClientResponse,Future<RequestOptions>> handler)

      Deprecated. instead use `HttpClientBuilder.withRedirectHandler(Function)`
      Set a redirect handler for the http client.

      The redirect handler is called when a `3xx` response is received and the request is configured to follow redirects with `HttpClientRequest.setFollowRedirects(boolean)`.

      The redirect handler is passed the `HttpClientResponse`, it can return an `HttpClientRequest` or `null`.

      - when null is returned, the original response is processed by the original request response handler
      - when a new `Future<HttpClientRequest>` is returned, the client will send this new request
      The new request will get a copy of the previous request headers unless headers are set. In this case, the client assumes that the redirect handler exclusively managers the headers of the new request.

      The handler must return a `Future<HttpClientRequest>` unsent so the client can further configure it and send it.

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

    - #### redirectHandler

          @Deprecated
          java.util.function.Function<HttpClientResponse,Future<RequestOptions>> redirectHandler()

      Deprecated.
      Returns:
        the current redirect handler.

    - #### close

          void close(Handler<AsyncResult<Void>> handler)

      Close the client. Closing will close down any pooled connections. Clients should always be closed after use.

    - #### close

          Future<Void> close()

      Like `close(Handler)` but returns a `Future` of the asynchronous result

Copyright © 2025 Eclipse. All rights reserved.