com.arangodb.shaded.vertx.core.http.HttpClient Maven / Gradle / Ivy
/*
* Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
* which is available at https://www.apache.org/licenses/LICENSE-2.0.
*
* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
*/
package com.arangodb.shaded.vertx.core.http;
import com.arangodb.shaded.vertx.codegen.annotations.Fluent;
import com.arangodb.shaded.vertx.codegen.annotations.GenIgnore;
import com.arangodb.shaded.vertx.codegen.annotations.VertxGen;
import com.arangodb.shaded.vertx.core.AsyncResult;
import com.arangodb.shaded.vertx.core.Future;
import com.arangodb.shaded.vertx.core.Handler;
import com.arangodb.shaded.vertx.core.MultiMap;
import com.arangodb.shaded.vertx.core.buffer.Buffer;
import com.arangodb.shaded.vertx.core.metrics.Measured;
import com.arangodb.shaded.vertx.core.net.SSLOptions;
import com.arangodb.shaded.vertx.core.net.SocketAddress;
import com.arangodb.shaded.vertx.core.streams.ReadStream;
import java.util.List;
import java.util.function.Function;
import java.util.function.Predicate;
/**
* An asynchronous HTTP client.
*
* It allows you to make requests to HTTP servers, and a single client can make requests to any server.
*
* It also allows you to open WebSockets to servers.
*
* The client can also pool HTTP connections.
*
* For pooling to occur, keep-alive must be true on the {@link com.arangodb.shaded.vertx.core.http.HttpClientOptions} (default is true).
* In this case connections will be pooled and re-used if there are pending HTTP requests waiting to get a connection,
* otherwise they will be closed.
*
* 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 also supports pipe-lining of requests. Pipe-lining means another request is sent on the same connection
* before the response from the preceding one has returned. Pipe-lining is not appropriate for all requests.
*
* To enable pipe-lining, it must be enabled on the {@link com.arangodb.shaded.vertx.core.http.HttpClientOptions} (default is false).
*
* When pipe-lining is enabled the connection will be automatically closed when all in-flight responses have returned
* and there are no outstanding pending requests to write.
*
* The client is designed to be reused between requests.
*
* @author Tim Fox
*/
@VertxGen
public interface HttpClient extends Measured {
/**
* Create an HTTP request to send to the server. The {@code handler}
* is called when the request is ready to be sent.
*
* @param options the request options
* @param handler the handler called when the request is ready to be sent
*/
void request(RequestOptions options, Handler> handler);
/**
* Like {@link #request(RequestOptions, Handler)} but returns a {@code Future} of the asynchronous result
*/
Future request(RequestOptions options);
/**
* Create an HTTP request to send to the server at the {@code host} and {@code port}. The {@code handler}
* is called when the request is ready to be sent.
*
* @param method the HTTP method
* @param port the port
* @param host the host
* @param requestURI the relative URI
* @param handler the handler called when the request is ready to be sent
*/
void request(HttpMethod method, int port, String host, String requestURI, Handler> handler);
/**
* Like {@link #request(HttpMethod, int, String, String, Handler)} but returns a {@code Future} of the asynchronous result
*/
Future request(HttpMethod method, int port, String host, String requestURI);
/**
* Create an HTTP request to send to the server at the {@code host} and default port. The {@code handler}
* is called when the request is ready to be sent.
*
* @param method the HTTP method
* @param host the host
* @param requestURI the relative URI
* @param handler the handler called when the request is ready to be sent
*/
void request(HttpMethod method, String host, String requestURI, Handler> handler);
/**
* Like {@link #request(HttpMethod, String, String, Handler)} but returns a {@code Future} of the asynchronous result
*/
Future request(HttpMethod method, String host, String requestURI);
/**
* Create an HTTP request to send to the server at the default host and port. The {@code handler}
* is called when the request is ready to be sent.
*
* @param method the HTTP method
* @param requestURI the relative URI
* @param handler the handler called when the request is ready to be sent
*/
void request(HttpMethod method, String requestURI, Handler> handler);
/**
* Like {@link #request(HttpMethod, String, Handler)} but returns a {@code Future} of the asynchronous result
*/
Future request(HttpMethod method, String requestURI);
/**
* Connect a WebSocket to the specified port, host and relative request URI
* @param port the port
* @param host the host
* @param requestURI the relative URI
* @param handler handler that will be called with the WebSocket when connected
*/
void webSocket(int port, String host, String requestURI, Handler> handler);
/**
* Like {@link #webSocket(int, String, String, Handler)} but returns a {@code Future} of the asynchronous result
*/
Future webSocket(int port, String host, String requestURI);
/**
* Connect a WebSocket to the host and relative request URI and default port
* @param host the host
* @param requestURI the relative URI
* @param handler handler that will be called with the WebSocket when connected
*/
void webSocket(String host, String requestURI, Handler> handler);
/**
* Like {@link #webSocket(String, String, Handler)} but returns a {@code Future} of the asynchronous result
*/
Future webSocket(String host, String requestURI);
/**
* Connect a WebSocket at the relative request URI using the default host and port
* @param requestURI the relative URI
* @param handler handler that will be called with the WebSocket when connected
*/
void webSocket(String requestURI, Handler> handler);
/**
* Like {@link #webSocket(String, Handler)} but returns a {@code Future} of the asynchronous result
*/
Future webSocket(String requestURI);
/**
* Connect a WebSocket with the specified options.
*
* @param options the request options
*/
void webSocket(WebSocketConnectOptions options, Handler> handler);
/**
* Like {@link #webSocket(WebSocketConnectOptions, Handler)} but returns a {@code Future} of the asynchronous result
*/
Future webSocket(WebSocketConnectOptions options);
/**
* Connect a WebSocket with the specified absolute url, with the specified headers, using
* the specified version of WebSockets, and the specified WebSocket sub protocols.
*
* @param url the absolute url
* @param headers the headers
* @param version the WebSocket version
* @param subProtocols the subprotocols to use
* @param handler handler that will be called if WebSocket connection fails
*/
void webSocketAbs(String url, MultiMap headers, WebsocketVersion version, List subProtocols, Handler> handler);
/**
* Like {@link #webSocketAbs(String, MultiMap, WebsocketVersion, List, Handler)} but returns a {@code Future} of the asynchronous result
*/
Future webSocketAbs(String url, MultiMap headers, WebsocketVersion version, List subProtocols);
/**
* Update the client SSL options.
*
* Update only happens if the SSL options is valid.
*
* @param options the new SSL options
* @return a future signaling the update success
*/
Future updateSSLOptions(SSLOptions options);
/**
* Like {@link #updateSSLOptions(SSLOptions)} but supplying a handler that will be called when the update
* happened (or has failed).
*
* @param options the new SSL options
* @param handler the update handler
*/
default void updateSSLOptions(SSLOptions options, Handler> handler) {
Future fut = updateSSLOptions(options);
if (handler != null) {
fut.onComplete(handler);
}
}
/**
* Set a connection handler for the client. This handler is called when a new connection is established.
*
* @return a reference to this, so the API can be used fluently
*/
@Fluent
HttpClient connectionHandler(Handler handler);
/**
* Set a redirect handler for the http client.
*
* The redirect handler is called when a {@code 3xx} response is received and the request is configured to
* follow redirects with {@link HttpClientRequest#setFollowRedirects(boolean)}.
*
* The redirect handler is passed the {@link HttpClientResponse}, it can return an {@link HttpClientRequest} or {@code null}.
*
* - when null is returned, the original response is processed by the original request response handler
* - when a new {@code Future
} 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 {@code Future} unsent so the client can further configure it and send it.
*
* @param handler the new redirect handler
* @return a reference to this, so the API can be used fluently
*/
@Fluent
HttpClient redirectHandler(Function> handler);
/**
* @return the current redirect handler.
*/
@GenIgnore
Function> redirectHandler();
/**
* Close the client. Closing will close down any pooled connections.
* Clients should always be closed after use.
*/
void close(Handler> handler);
/**
* Like {@link #close(Handler)} but returns a {@code Future} of the asynchronous result
*/
Future close();
}