More doc and deprecate HttpClient#webSocket methods

src/main/asciidoc/http.adoc

@@ -805,7 +805,7 @@ You can configure compressors according to your needs
 
 === Creating an HTTP client
 
-You create an {@link io.vertx.core.http.HttpPool} instance with default options as follows:
+You create an {@link io.vertx.core.http.HttpClientPool} instance with default options as follows:
 
 [source,$lang]
 ----

src/main/java/examples/HTTP2Examples.java

@@ -209,7 +209,7 @@ public void example18(HttpClientRequest request) {
     HttpConnection connection = request.connection();
   }
 
-  public void example19(HttpPool pool) {
+  public void example19(HttpClientPool pool) {
     pool.connectionHandler(connection -> {
       System.out.println("Connected to the server");
     });

src/main/java/examples/HTTPExamples.java

@@ -321,22 +321,22 @@ public void sendHttpServerResponse(Vertx vertx) {
   }
 
   public void example28(Vertx vertx) {
-    HttpClient client = vertx.createHttpPool();
+    HttpClient client = vertx.createHttpClientPool();
   }
 
   public void example29(Vertx vertx) {
     HttpClientOptions options = new HttpClientOptions().setKeepAlive(false);
-    HttpClient client = vertx.createHttpPool(options);
+    HttpClient client = vertx.createHttpClientPool(options);
   }
 
   public void examplePoolConfiguration(Vertx vertx) {
     PoolOptions options = new PoolOptions().setHttp1MaxSize(10);
-    HttpClient client = vertx.createHttpPool(options);
+    HttpClient client = vertx.createHttpClientPool(options);
   }
 
   public void exampleClientLogging(Vertx vertx) {
     HttpClientOptions options = new HttpClientOptions().setLogActivity(true);
-    HttpClient client = vertx.createHttpPool(options);
+    HttpClient client = vertx.createHttpClientPool(options);
   }
 
   public void example30(HttpClient client) {
@@ -355,7 +355,7 @@ public void example31(Vertx vertx) {
     HttpClientOptions options = new HttpClientOptions().setDefaultHost("wibble.com");
 
     // Can also set default port if you want...
-    HttpClient client = vertx.createHttpPool(options);
+    HttpClient client = vertx.createHttpClientPool(options);
     client
       .request(HttpMethod.GET, "/some-uri")
       .onComplete(ar1 -> {
@@ -375,7 +375,7 @@ public void example31(Vertx vertx) {
 
   public void example32(Vertx vertx) {
 
-    HttpClient client = vertx.createHttpPool();
+    HttpClient client = vertx.createHttpClientPool();
 
     // Write some headers using the headers multi-map
     MultiMap headers = HttpHeaders.set("content-type", "application/json").set("other-header", "foo");
@@ -481,7 +481,7 @@ public void sendRequest04(HttpClientRequest request, ReadStream<Buffer> stream)
       });
   }
   public void example34(Vertx vertx, String body) {
-    HttpClient client = vertx.createHttpPool();
+    HttpClient client = vertx.createHttpClientPool();
 
     client.request(HttpMethod.POST, "some-uri")
       .onSuccess(request -> {
@@ -776,7 +776,7 @@ public void exampleFollowRedirect01(HttpClient client) {
 
   public void exampleFollowRedirect02(Vertx vertx) {
 
-    HttpClient client = vertx.createHttpPool(
+    HttpClient client = vertx.createHttpClientPool(
         new HttpClientOptions()
             .setMaxRedirects(32));
 
@@ -804,7 +804,7 @@ private String resolveURI(String base, String uriRef) {
     throw new UnsupportedOperationException();
   }
 
-  public void exampleFollowRedirect03(HttpPool pool) {
+  public void exampleFollowRedirect03(HttpClientPool pool) {
 
     pool.redirectHandler(response -> {
 
@@ -1067,7 +1067,7 @@ public void example58(Vertx vertx) {
         .setProxyOptions(new ProxyOptions().setType(ProxyType.HTTP)
             .setHost("localhost").setPort(3128)
             .setUsername("username").setPassword("secret"));
-    HttpClient client = vertx.createHttpPool(options);
+    HttpClient client = vertx.createHttpClientPool(options);
 
   }
 
@@ -1077,7 +1077,7 @@ public void example59(Vertx vertx) {
         .setProxyOptions(new ProxyOptions().setType(ProxyType.SOCKS5)
             .setHost("localhost").setPort(1080)
             .setUsername("username").setPassword("secret"));
-    HttpClient client = vertx.createHttpPool(options);
+    HttpClient client = vertx.createHttpClientPool(options);
 
   }
 
@@ -1089,7 +1089,7 @@ public void nonProxyHosts(Vertx vertx) {
         .setUsername("username").setPassword("secret"))
       .addNonProxyHost("*.foo.com")
       .addNonProxyHost("localhost");
-    HttpClient client = vertx.createHttpPool(options);
+    HttpClient client = vertx.createHttpClientPool(options);
 
   }
 
@@ -1110,7 +1110,7 @@ public void example60(Vertx vertx) {
 
     HttpClientOptions options = new HttpClientOptions()
         .setProxyOptions(new ProxyOptions().setType(ProxyType.HTTP));
-    HttpClient client = vertx.createHttpPool(options);
+    HttpClient client = vertx.createHttpClientPool(options);
     client
       .request(HttpMethod.GET, "ftp://ftp.gnu.org/gnu/")
       .onComplete(ar -> {
@@ -1153,7 +1153,7 @@ public void serversharing(Vertx vertx) {
   public void serversharingclient(Vertx vertx) {
     vertx.setPeriodic(100, (l) -> {
       vertx
-        .createHttpPool()
+        .createHttpClientPool()
         .request(HttpMethod.GET, 8080, "localhost", "/")
         .onComplete(ar1 -> {
           if (ar1.succeeded()) {
@@ -1221,7 +1221,7 @@ public static void compressorConfig() {
   }
 
   public static void httpClientSharing1(Vertx vertx) {
-    HttpClient client = vertx.createHttpPool(new HttpClientOptions().setShared(true));
+    HttpClient client = vertx.createHttpClientPool(new HttpClientOptions().setShared(true));
     vertx.deployVerticle(() -> new AbstractVerticle() {
       @Override
       public void start() throws Exception {
@@ -1238,7 +1238,7 @@ public void start() {
         // Get or create a shared client
         // this actually creates a lease to the client
         // when the verticle is undeployed, the lease will be released automaticaly
-        client = vertx.createHttpPool(new HttpClientOptions().setShared(true).setName("my-client"));
+        client = vertx.createHttpClientPool(new HttpClientOptions().setShared(true).setName("my-client"));
       }
     }, new DeploymentOptions().setInstances(4));
   }
@@ -1249,7 +1249,7 @@ public static void httpClientSharing3(Vertx vertx) {
       @Override
       public void start() {
         // The client creates and use two event-loops for 4 instances
-        client = vertx.createHttpPool(new HttpClientOptions().setPoolEventLoopSize(2).setShared(true).setName("my-client"));
+        client = vertx.createHttpClientPool(new HttpClientOptions().setPoolEventLoopSize(2).setShared(true).setName("my-client"));
       }
     }, new DeploymentOptions().setInstances(4));
   }

src/main/java/io/vertx/core/http/HttpClient.java

@@ -29,25 +29,9 @@
  * <p>
  * It allows you to make requests to HTTP servers, and a single client can make requests to any server.
  * <p>
- * It also allows you to open WebSockets to servers.
- * <p>
- * The client can also pool HTTP connections.
- * <p>
- * For pooling to occur, keep-alive must be true on the {@link io.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.
- * <p>
  * 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.
  * <p>
- * 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.
- * <p>
- * To enable pipe-lining, it must be enabled on the {@link io.vertx.core.http.HttpClientOptions} (default is false).
- * <p>
- * 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.
- * <p>
  * The client is designed to be reused between requests.
  *
  * @author <a href="http://tfox.org">Tim Fox</a>
@@ -123,49 +107,65 @@ public interface HttpClient extends Measured {
    * @param host  the host
    * @param requestURI  the relative URI
    * @param handler  handler that will be called with the WebSocket when connected
+   * @deprecated instead use {@link WebSocketClient#connect(int, String, String, Handler)}
    */
+  @Deprecated
   void webSocket(int port, String host, String requestURI, Handler<AsyncResult<WebSocket>> handler);
 
   /**
    * Like {@link #webSocket(int, String, String, Handler)} but returns a {@code Future} of the asynchronous result
+   * @deprecated instead use {@link WebSocketClient#connect(int, String, String)}
    */
+  @Deprecated
   Future<WebSocket> 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
+   * @deprecated instead use {@link WebSocketClient#connect(int, String, String, Handler)}
    */
+  @Deprecated
   void webSocket(String host, String requestURI, Handler<AsyncResult<WebSocket>> handler);
 
   /**
    * Like {@link #webSocket(String, String, Handler)} but returns a {@code Future} of the asynchronous result
+   * @deprecated instead use {@link WebSocketClient#connect(int, String, String)}
    */
+  @Deprecated
   Future<WebSocket> 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
+   * @deprecated instead use {@link WebSocketClient#connect(int, String, String, Handler)}
    */
+  @Deprecated
   void webSocket(String requestURI, Handler<AsyncResult<WebSocket>> handler);
 
   /**
    * Like {@link #webSocket(String, Handler)} but returns a {@code Future} of the asynchronous result
+   * @deprecated instead use {@link WebSocketClient#connect(int, String, String)}
    */
+  @Deprecated
   Future<WebSocket> webSocket(String requestURI);
 
   /**
    * Connect a WebSocket with the specified options.
    *
    * @param options  the request options
+   * @deprecated instead use {@link WebSocketClient#connect(WebSocketConnectOptions, Handler)}
    */
+  @Deprecated
   void webSocket(WebSocketConnectOptions options, Handler<AsyncResult<WebSocket>> handler);
 
   /**
    * Like {@link #webSocket(WebSocketConnectOptions, Handler)} but returns a {@code Future} of the asynchronous result
+   * @deprecated instead use {@link WebSocketClient#connect(WebSocketConnectOptions)}
    */
+  @Deprecated
   Future<WebSocket> webSocket(WebSocketConnectOptions options);
 
   /**
@@ -177,12 +177,16 @@ public interface HttpClient extends Measured {
    * @param version        the WebSocket version
    * @param subProtocols   the subprotocols to use
    * @param handler handler that will be called if WebSocket connection fails
+   * @deprecated instead use {@link WebSocketClient#connect(WebSocketConnectOptions, Handler)}
    */
+  @Deprecated
   void webSocketAbs(String url, MultiMap headers, WebsocketVersion version, List<String> subProtocols, Handler<AsyncResult<WebSocket>> handler);
 
   /**
    * Like {@link #webSocketAbs(String, MultiMap, WebsocketVersion, List, Handler)} but returns a {@code Future} of the asynchronous result
+   * @deprecated instead use {@link WebSocketClient#connect(WebSocketConnectOptions)}
    */
+  @Deprecated
   Future<WebSocket> webSocketAbs(String url, MultiMap headers, WebsocketVersion version, List<String> subProtocols);
 
   /**

src/main/java/io/vertx/core/http/HttpClientPool.java

@@ -18,6 +18,13 @@
 
 import java.util.function.Function;
 
+/**
+ * An asynchronous HTTP client.
+ * <p>
+ * It allows you to make requests to HTTP servers, and a single client can make requests to any server.
+ *
+ * @author <a href="http://tfox.org">Tim Fox</a>
+ */
 @VertxGen
 public interface HttpClientPool extends HttpClient {