/*
 * Copyright 2014 Red Hat, Inc.
 *
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  and Apache License v2.0 which accompanies this distribution.
 *
 *  The Eclipse Public License is available at
 *  http://www.eclipse.org/legal/epl-v10.html
 *
 *  The Apache License v2.0 is available at
 *  http://www.opensource.org/licenses/apache2.0.php
 *
 *  You may elect to redistribute this code under either of these licenses.
 */
package io.vertx.ext.web.client;

import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.Vertx;
import io.vertx.core.buffer.Buffer;
import io.vertx.core.http.HttpClient;
import io.vertx.core.http.HttpMethod;
import io.vertx.core.http.RequestOptions;
import io.vertx.core.http.impl.HttpClientImpl;
import io.vertx.core.net.SocketAddress;
import io.vertx.ext.web.client.impl.WebClientBase;

An asynchronous HTTP / HTTP/2 client called WebClient. 

The web client makes easy to do HTTP request/response interactions with a web server, and provides advanced
features like:

  
Json body encoding / decoding
  
request/response pumping
  
error handling

 The web client does not deprecate the HttpClient, it is actually based on it and therefore inherits its configuration and great features like pooling. The HttpClient should be used when fine grained control over the HTTP requests/response is necessary. 
Author:
Julien Viet/**
 * An asynchronous HTTP / HTTP/2 client called {@code WebClient}.
 * <p>
 * The web client makes easy to do HTTP request/response interactions with a web server, and provides advanced
 * features like:
 * <ul>
 *   <li>Json body encoding / decoding</li>
 *   <li>request/response pumping</li>
 *   <li>error handling</li>
 * </ul>
 * <p>
 * The web client does not deprecate the {@link HttpClient}, it is actually based on it and therefore inherits
 * its configuration and great features like pooling. The {@code HttpClient} should be used when fine grained control over the HTTP
 * requests/response is necessary.
 *
 * @author <a href="mailto:julien@julienviet.com">Julien Viet</a>
 */
@VertxGen
public interface WebClient {

  
Create a web client using the provided vertx instance and default options. 
Params:
vertx – the vertx instance
Returns:
the created web client/**
   * Create a web client using the provided {@code vertx} instance and default options.
   *
   * @param vertx the vertx instance
   * @return the created web client
   */
  static WebClient create(Vertx vertx) {
    WebClientOptions options = new WebClientOptions();
    return create(vertx, options);
  }

  
Create a web client using the provided vertx instance. 
Params:
vertx –   the vertx instance
options – the Web Client options
Returns:
the created web client/**
   * Create a web client using the provided {@code vertx} instance.
   *
   * @param vertx   the vertx instance
   * @param options the Web Client options
   * @return the created web client
   */
  static WebClient create(Vertx vertx, WebClientOptions options) {
    return new WebClientBase(vertx.createHttpClient(options), options);
  }

  
Wrap an httpClient with a web client and default options. 
Params:
httpClient – the HttpClient to wrap
Returns:
the web client/**
   * Wrap an {@code httpClient} with a web client and default options.
   *
   * @param httpClient the {@link HttpClient} to wrap
   * @return the web client
   */
  static WebClient wrap(HttpClient httpClient) {
    return wrap(httpClient, new WebClientOptions());
  }

  
Wrap an httpClient with a web client and default options. 
 Only the specific web client portion of the options is used, the HttpClientOptions of the httpClient is reused. 
Params:
httpClient – the HttpClient to wrap
options –    the Web Client options
Returns:
the web client/**
   * Wrap an {@code httpClient} with a web client and default options.
   * <p>
   * Only the specific web client portion of the {@code options} is used, the {@link io.vertx.core.http.HttpClientOptions}
   * of the {@code httpClient} is reused.
   *
   * @param httpClient the {@link HttpClient} to wrap
   * @param options    the Web Client options
   * @return the web client
   */
  static WebClient wrap(HttpClient httpClient, WebClientOptions options) {
    WebClientOptions actualOptions = new WebClientOptions(((HttpClientImpl) httpClient).getOptions());
    actualOptions.init(options);
    return new WebClientBase(httpClient, actualOptions);
  }

  
Create an HTTP request to send to the server at the specified host and port.
Params:
method –  the HTTP method
port –  the port
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP request to send to the server at the specified host and port.
   * @param method  the HTTP method
   * @param port  the port
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> request(HttpMethod method, int port, String host, String requestURI);

  
Like request(HttpMethod, int, String, String) using the serverAddress parameter to connect to the server instead of the port and host parameters. 
 The request host header will still be created from the port and host parameters. 
 Use SocketAddress.domainSocketAddress(String) to connect to a unix domain socket server. /**
   * Like {@link #request(HttpMethod, int, String, String)} using the {@code serverAddress} parameter to connect to the
   * server instead of the {@code port} and {@code host} parameters.
   * <p>
   * The request host header will still be created from the {@code port} and {@code host} parameters.
   * <p>
   * Use {@link SocketAddress#domainSocketAddress(String)} to connect to a unix domain socket server.
   */
  HttpRequest<Buffer> request(HttpMethod method, SocketAddress serverAddress, int port, String host, String requestURI);

  
Create an HTTP request to send to the server at the specified host and default port.
Params:
method –  the HTTP method
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP request to send to the server at the specified host and default port.
   * @param method  the HTTP method
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> request(HttpMethod method, String host, String requestURI);

  
Like request(HttpMethod, String, String) using the serverAddress parameter to connect to the server instead of the default port and host parameter. 
 The request host header will still be created from the default port and host parameter. 
 Use SocketAddress.domainSocketAddress(String) to connect to a unix domain socket server. /**
   * Like {@link #request(HttpMethod, String, String)} using the {@code serverAddress} parameter to connect to the
   * server instead of the default port and {@code host} parameter.
   * <p>
   * The request host header will still be created from the default port and {@code host} parameter.
   * <p>
   * Use {@link SocketAddress#domainSocketAddress(String)} to connect to a unix domain socket server.
   */
  HttpRequest<Buffer> request(HttpMethod method, SocketAddress serverAddress, String host, String requestURI);

  
Create an HTTP request to send to the server at the default host and port.
Params:
method –  the HTTP method
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP request to send to the server at the default host and port.
   * @param method  the HTTP method
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> request(HttpMethod method, String requestURI);

  
Like request(HttpMethod, String) using the serverAddress parameter to connect to the server instead of the default port and default host. 

The request host header will still be created from the default port and default host.
 Use SocketAddress.domainSocketAddress(String) to connect to a unix domain socket server. /**
   * Like {@link #request(HttpMethod, String)} using the {@code serverAddress} parameter to connect to the
   * server instead of the default port and default host.
   * <p>
   * The request host header will still be created from the default port and default host.
   * <p>
   * Use {@link SocketAddress#domainSocketAddress(String)} to connect to a unix domain socket server.
   */
  HttpRequest<Buffer> request(HttpMethod method, SocketAddress serverAddress, String requestURI);

  
Create an HTTP request to send to the server at the specified host and port.
Params:
method –  the HTTP method
options –  the request options
Returns:
 an HTTP client request object/**
   * Create an HTTP request to send to the server at the specified host and port.
   * @param method  the HTTP method
   * @param options  the request options
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> request(HttpMethod method, RequestOptions options);

  
Like request(HttpMethod, RequestOptions) using the serverAddress parameter to connect to the server instead of the options parameter. 
 The request host header will still be created from the options parameter. 
 Use SocketAddress.domainSocketAddress(String) to connect to a unix domain socket server. /**
   * Like {@link #request(HttpMethod, RequestOptions)} using the {@code serverAddress} parameter to connect to the
   * server instead of the {@code options} parameter.
   * <p>
   * The request host header will still be created from the {@code options} parameter.
   * <p>
   * Use {@link SocketAddress#domainSocketAddress(String)} to connect to a unix domain socket server.
   */
  HttpRequest<Buffer> request(HttpMethod method, SocketAddress serverAddress, RequestOptions options);

  
Create an HTTP request to send to the server using an absolute URI
Params:
method –  the HTTP method
absoluteURI –  the absolute URI
Returns:
 an HTTP client request object/**
   * Create an HTTP request to send to the server using an absolute URI
   * @param method  the HTTP method
   * @param absoluteURI  the absolute URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> requestAbs(HttpMethod method, String absoluteURI);

  
Like requestAbs(HttpMethod, String) using the serverAddress parameter to connect to the server instead of the absoluteURI parameter. 
 The request host header will still be created from the absoluteURI parameter. 
 Use SocketAddress.domainSocketAddress(String) to connect to a unix domain socket server. /**
   * Like {@link #requestAbs(HttpMethod, String)} using the {@code serverAddress} parameter to connect to the
   * server instead of the {@code absoluteURI} parameter.
   * <p>
   * The request host header will still be created from the {@code absoluteURI} parameter.
   * <p>
   * Use {@link SocketAddress#domainSocketAddress(String)} to connect to a unix domain socket server.
   */
  HttpRequest<Buffer> requestAbs(HttpMethod method, SocketAddress serverAddress, String absoluteURI);

  
Create an HTTP GET request to send to the server at the default host and port.
Params:
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP GET request to send to the server at the default host and port.
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> get(String requestURI);

  
Create an HTTP GET request to send to the server at the specified host and port.
Params:
port –  the port
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP GET request to send to the server at the specified host and port.
   * @param port  the port
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> get(int port, String host, String requestURI);

  
Create an HTTP GET request to send to the server at the specified host and default port.
Params:
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP GET request to send to the server at the specified host and default port.
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> get(String host, String requestURI);

  
Create an HTTP GET request to send to the server using an absolute URI, specifying a response handler to receive
the response
Params:
absoluteURI –  the absolute URI
Returns:
 an HTTP client request object/**
   * Create an HTTP GET request to send to the server using an absolute URI, specifying a response handler to receive
   * the response
   * @param absoluteURI  the absolute URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> getAbs(String absoluteURI);

  
Create an HTTP POST request to send to the server at the default host and port.
Params:
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP POST request to send to the server at the default host and port.
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> post(String requestURI);

  
Create an HTTP POST request to send to the server at the specified host and port.
Params:
port –  the port
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP POST request to send to the server at the specified host and port.
   * @param port  the port
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> post(int port, String host, String requestURI);

  
Create an HTTP POST request to send to the server at the specified host and default port.
Params:
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP POST request to send to the server at the specified host and default port.
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> post(String host, String requestURI);

  
Create an HTTP POST request to send to the server using an absolute URI, specifying a response handler to receive
the response
Params:
absoluteURI –  the absolute URI
Returns:
 an HTTP client request object/**
   * Create an HTTP POST request to send to the server using an absolute URI, specifying a response handler to receive
   * the response
   * @param absoluteURI  the absolute URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> postAbs(String absoluteURI);

  
Create an HTTP PUT request to send to the server at the default host and port.
Params:
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP PUT request to send to the server at the default host and port.
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> put(String requestURI);

  
Create an HTTP PUT request to send to the server at the specified host and port.
Params:
port –  the port
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP PUT request to send to the server at the specified host and port.
   * @param port  the port
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> put(int port, String host, String requestURI);

  
Create an HTTP PUT request to send to the server at the specified host and default port.
Params:
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP PUT request to send to the server at the specified host and default port.
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> put(String host, String requestURI);

  
Create an HTTP PUT request to send to the server using an absolute URI, specifying a response handler to receive
the response
Params:
absoluteURI –  the absolute URI
Returns:
 an HTTP client request object/**
   * Create an HTTP PUT request to send to the server using an absolute URI, specifying a response handler to receive
   * the response
   * @param absoluteURI  the absolute URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> putAbs(String absoluteURI);

  
Create an HTTP DELETE request to send to the server at the default host and port.
Params:
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP DELETE request to send to the server at the default host and port.
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> delete(String requestURI);

  
Create an HTTP DELETE request to send to the server at the specified host and port.
Params:
port –  the port
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP DELETE request to send to the server at the specified host and port.
   * @param port  the port
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> delete(int port, String host, String requestURI);

  
Create an HTTP DELETE request to send to the server at the specified host and default port.
Params:
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP DELETE request to send to the server at the specified host and default port.
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> delete(String host, String requestURI);

  
Create an HTTP DELETE request to send to the server using an absolute URI, specifying a response handler to receive
the response
Params:
absoluteURI –  the absolute URI
Returns:
 an HTTP client request object/**
   * Create an HTTP DELETE request to send to the server using an absolute URI, specifying a response handler to receive
   * the response
   * @param absoluteURI  the absolute URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> deleteAbs(String absoluteURI);

  
Create an HTTP PATCH request to send to the server at the default host and port.
Params:
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP PATCH request to send to the server at the default host and port.
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> patch(String requestURI);

  
Create an HTTP PATCH request to send to the server at the specified host and port.
Params:
port –  the port
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP PATCH request to send to the server at the specified host and port.
   * @param port  the port
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> patch(int port, String host, String requestURI);

  
Create an HTTP PATCH request to send to the server at the specified host and default port.
Params:
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP PATCH request to send to the server at the specified host and default port.
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> patch(String host, String requestURI);

  
Create an HTTP PATCH request to send to the server using an absolute URI, specifying a response handler to receive
the response
Params:
absoluteURI –  the absolute URI
Returns:
 an HTTP client request object/**
   * Create an HTTP PATCH request to send to the server using an absolute URI, specifying a response handler to receive
   * the response
   * @param absoluteURI  the absolute URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> patchAbs(String absoluteURI);

  
Create an HTTP HEAD request to send to the server at the default host and port.
Params:
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP HEAD request to send to the server at the default host and port.
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> head(String requestURI);

  
Create an HTTP HEAD request to send to the server at the specified host and port.
Params:
port –  the port
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP HEAD request to send to the server at the specified host and port.
   * @param port  the port
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> head(int port, String host, String requestURI);

  
Create an HTTP HEAD request to send to the server at the specified host and default port.
Params:
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create an HTTP HEAD request to send to the server at the specified host and default port.
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> head(String host, String requestURI);

  
Create an HTTP HEAD request to send to the server using an absolute URI, specifying a response handler to receive
the response
Params:
absoluteURI –  the absolute URI
Returns:
 an HTTP client request object/**
   * Create an HTTP HEAD request to send to the server using an absolute URI, specifying a response handler to receive
   * the response
   * @param absoluteURI  the absolute URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> headAbs(String absoluteURI);

  
Create a request with a custom HTTP method to send to the server at the default host and port.
Params:
customHttpMethod – custom HTTP Method
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create a request with a custom HTTP method to send to the server at the default host and port.
   *
   * @param customHttpMethod custom HTTP Method
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> raw(String customHttpMethod, String requestURI);

  
Create a request with a custom HTTP method to send to the server at the specified host and port.
Params:
customHttpMethod – custom HTTP Method
port –  the port
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create a request with a custom HTTP method to send to the server at the specified host and port.
   *
   * @param customHttpMethod custom HTTP Method
   * @param port  the port
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> raw(String customHttpMethod, int port, String host, String requestURI);

  
Create a request with a custom HTTP method  to send to the server at the specified host and default port.
Params:
customHttpMethod – custom HTTP Method
host –  the host
requestURI –  the relative URI
Returns:
 an HTTP client request object/**
   * Create a request with a custom HTTP method  to send to the server at the specified host and default port.
   *
   * @param customHttpMethod custom HTTP Method
   * @param host  the host
   * @param requestURI  the relative URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> raw(String customHttpMethod, String host, String requestURI);

  
Create a request with a custom HTTP method  to send to the server using an absolute URI, specifying a response handler to receive
the response
Params:
customHttpMethod – custom HTTP Method
absoluteURI –  the absolute URI
Returns:
 an HTTP client request object/**
   * Create a request with a custom HTTP method  to send to the server using an absolute URI, specifying a response handler to receive
   * the response
   *
   * @param customHttpMethod custom HTTP Method
   * @param absoluteURI  the absolute URI
   * @return  an HTTP client request object
   */
  HttpRequest<Buffer> rawAbs(String customHttpMethod, String absoluteURI);

  
Close the client. Closing will close down any pooled connections.
Clients should always be closed after use.
/**
   * Close the client. Closing will close down any pooled connections.
   * Clients should always be closed after use.
   */
  void close();
}