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

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