Introduce a client builder to replace static pool methods.

Author: vietj

vertx-pg-client/src/main/java/examples/PgClientExamples.java

@@ -22,10 +22,7 @@
 import io.vertx.core.json.JsonObject;
 import io.vertx.core.net.PemTrustOptions;
 import io.vertx.docgen.Source;
-import io.vertx.pgclient.PgConnectOptions;
-import io.vertx.pgclient.PgConnection;
-import io.vertx.pgclient.PgPool;
-import io.vertx.pgclient.SslMode;
+import io.vertx.pgclient.*;
 import io.vertx.pgclient.pubsub.PgSubscriber;
 import io.vertx.sqlclient.*;
 import io.vertx.sqlclient.data.Numeric;
@@ -59,7 +56,7 @@ public void gettingStarted() {
       .setMaxSize(5);
 
     // Create the client pool
-    SqlClient client = PgPool.client(connectOptions, poolOptions);
+    SqlClient client = PgBuilder.client().config(poolOptions).connectingTo(connectOptions).build();
 
     // A simple query
     client
@@ -81,7 +78,7 @@ public void gettingStarted() {
   public void configureFromEnv(Vertx vertx) {
 
     // Create the pool from the environment variables
-    PgPool pool = PgPool.pool();
+    Pool pool = PgBuilder.pool().build();
 
     // Create the connection from the environment variables
     PgConnection.connect(vertx)
@@ -104,7 +101,7 @@ public void configureFromDataObject(Vertx vertx) {
     PoolOptions poolOptions = new PoolOptions().setMaxSize(5);
 
     // Create the pool from the data object
-    PgPool pool = PgPool.pool(vertx, connectOptions, poolOptions);
+    Pool pool = PgBuilder.pool().connectingTo(connectOptions).config(poolOptions).using(vertx).build();
 
     pool.getConnection()
       .onComplete(ar -> {
@@ -128,7 +125,7 @@ public void configureFromUri(Vertx vertx) {
     String connectionUri = "postgresql://dbuser:secretpassword@database.server.com:5432/mydb";
 
     // Create the pool from the connection URI
-    PgPool pool = PgPool.pool(connectionUri);
+    Pool pool = PgBuilder.pool().connectingTo(PgConnectOptions.fromUri(connectionUri)).build();
 
     // Create the connection from the connection URI
     PgConnection
@@ -153,7 +150,7 @@ public void connecting01() {
       .setMaxSize(5);
 
     // Create the pooled client
-    SqlClient client = PgPool.client(connectOptions, poolOptions);
+    SqlClient client = PgBuilder.client().config(poolOptions).connectingTo(connectOptions).build();
   }
 
   public void connecting02(Vertx vertx) {
@@ -171,10 +168,10 @@ public void connecting02(Vertx vertx) {
       .setMaxSize(5);
 
     // Create the pooled client
-    SqlClient client = PgPool.client(vertx, connectOptions, poolOptions);
+    SqlClient client = PgBuilder.client().config(poolOptions).connectingTo(connectOptions).using(vertx).build();
   }
 
-  public void connecting03(PgPool client) {
+  public void connecting03(Pool client) {
 
     // Close the pooled client and all the associated resources
     client.close();
@@ -195,7 +192,12 @@ public void connecting04(Vertx vertx) {
       .setMaxSize(5);
 
     // Create the pooled client
-    PgPool pool = PgPool.pool(vertx, connectOptions, poolOptions);
+    Pool pool = PgBuilder
+      .pool()
+      .config(poolOptions)
+      .connectingTo(connectOptions)
+      .using(vertx)
+      .build();
 
     // Get a connection from the pool
     pool.getConnection().compose(conn -> {
@@ -259,19 +261,29 @@ public void connecting05(Vertx vertx) {
   }
 
   public void clientPipelining(Vertx vertx, PgConnectOptions connectOptions, PoolOptions poolOptions) {
-    PgPool pool = PgPool.pool(vertx, connectOptions.setPipeliningLimit(16), poolOptions);
+    Pool pool = PgBuilder
+      .pool()
+      .connectingTo(connectOptions.setPipeliningLimit(16))
+      .config(poolOptions)
+      .using(vertx)
+      .build();
   }
 
   public void poolVersusPooledClient(Vertx vertx, String sql, PgConnectOptions connectOptions, PoolOptions poolOptions) {
 
     // Pooled client
-    SqlClient client = PgPool.client(vertx, connectOptions, poolOptions);
+    SqlClient client = PgBuilder.client().config(poolOptions).connectingTo(connectOptions).using(vertx).build();
 
     // Pipelined
     Future<RowSet<Row>> res1 = client.query(sql).execute();
 
     // Connection pool
-    PgPool pool = PgPool.pool(vertx, connectOptions, poolOptions);
+    Pool pool = PgBuilder
+      .pool()
+      .connectingTo(connectOptions)
+      .config(poolOptions)
+      .using(vertx)
+      .build();
 
     // Not pipelined
     Future<RowSet<Row>> res2 = pool.query(sql).execute();
@@ -291,11 +303,20 @@ public void unixDomainSockets(Vertx vertx) {
       .setMaxSize(5);
 
     // Create the pooled client
-    PgPool client = PgPool.pool(connectOptions, poolOptions);
+    Pool client = PgBuilder
+      .pool()
+      .connectingTo(connectOptions)
+      .config(poolOptions)
+      .build();
 
     // Create the pooled client with a vertx instance
     // Make sure the vertx instance has enabled native transports
-    PgPool client2 = PgPool.pool(vertx, connectOptions, poolOptions);
+    Pool client2 = PgBuilder
+      .pool()
+      .connectingTo(connectOptions)
+      .config(poolOptions)
+      .using(vertx)
+      .build();
   }
 
   public void reconnectAttempts(PgConnectOptions options) {

vertx-pg-client/src/main/java/examples/SqlClientExamples.java

@@ -22,11 +22,9 @@
 import io.vertx.core.Vertx;
 import io.vertx.core.tracing.TracingPolicy;
 import io.vertx.docgen.Source;
+import io.vertx.pgclient.PgBuilder;
 import io.vertx.pgclient.PgConnectOptions;
-import io.vertx.pgclient.PgPool;
-import io.vertx.pgclient.spi.PgDriver;
 import io.vertx.sqlclient.*;
-import io.vertx.sqlclient.spi.ConnectionFactory;
 
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -365,10 +363,10 @@ public void tracing01(PgConnectOptions options) {
   }
 
   public void poolConfig01(PgConnectOptions server1, PgConnectOptions server2, PgConnectOptions server3, PoolOptions options) {
-    PgPool pool = PgPool.pool(Arrays.asList(server1, server2, server3), options);
+    Pool pool = PgBuilder.pool().connectingTo(Arrays.asList(server1, server2, server3)).config(options).build();
   }
 
-  public void poolConfig02(PgPool pool, String sql) {
+  public void poolConfig02(Pool pool, String sql) {
     pool.connectHandler(conn -> {
       conn.query(sql).execute().onSuccess(res -> {
         // Release the connection to the pool, ready to be used by the application
@@ -378,7 +376,7 @@ public void poolConfig02(PgPool pool, String sql) {
   }
 
   public void poolSharing1(Vertx vertx, PgConnectOptions database, int maxSize) {
-    PgPool pool = PgPool.pool(database, new PoolOptions().setMaxSize(maxSize));
+    Pool pool = PgBuilder.pool().config(new PoolOptions().setMaxSize(maxSize)).connectingTo(database).build();
     vertx.deployVerticle(() -> new AbstractVerticle() {
       @Override
       public void start() throws Exception {
@@ -389,36 +387,44 @@ public void start() throws Exception {
 
   public void poolSharing2(Vertx vertx, PgConnectOptions database, int maxSize) {
     vertx.deployVerticle(() -> new AbstractVerticle() {
-      PgPool pool;
+      Pool pool;
       @Override
       public void start() {
         // Get or create a shared pool
         // this actually creates a lease to the pool
         // when the verticle is undeployed, the lease will be released automaticaly
-        pool = PgPool.pool(database, new PoolOptions()
-          .setMaxSize(maxSize)
-          .setShared(true)
-          .setName("my-pool"));
+        pool = PgBuilder.pool().
+          config(new PoolOptions()
+            .setMaxSize(maxSize)
+            .setShared(true)
+            .setName("my-pool")).connectingTo(database)
+          .build();
       }
     }, new DeploymentOptions().setInstances(4));
   }
 
   public static void poolSharing3(Vertx vertx, PgConnectOptions database, int maxSize) {
-    PgPool pool = PgPool.pool(database, new PoolOptions()
-      .setMaxSize(maxSize)
-      .setShared(true)
-      .setName("my-pool")
-      .setEventLoopSize(4));
+    Pool pool = PgBuilder.pool()
+      .config(new PoolOptions()
+        .setMaxSize(maxSize)
+        .setShared(true)
+        .setName("my-pool")
+        .setEventLoopSize(4)).connectingTo(database)
+      .build();
   }
 
   public void dynamicPoolConfig(Vertx vertx, PoolOptions poolOptions) {
-    PgPool pool = PgPool.pool(vertx, () -> {
-      Future<PgConnectOptions> connectOptions = retrieveOptions();
-      return connectOptions;
-    }, poolOptions);
+    Pool pool = PgBuilder.pool()
+      .config(poolOptions)
+      .connectingTo(() -> {
+        Future<SqlConnectOptions> connectOptions = retrieveOptions();
+        return connectOptions;
+      })
+      .using(vertx)
+      .build();
   }
 
-  private Future<PgConnectOptions> retrieveOptions() {
+  private Future<SqlConnectOptions> retrieveOptions() {
     return null;
   }
 }

vertx-pg-client/src/main/java/io/vertx/pgclient/PgBuilder.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright (C) 2017 Julien Viet
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package io.vertx.pgclient;
+
+import io.vertx.codegen.annotations.VertxGen;
+import io.vertx.core.Handler;
+import io.vertx.pgclient.impl.PgPoolOptions;
+import io.vertx.pgclient.spi.PgDriver;
+import io.vertx.sqlclient.*;
+import io.vertx.sqlclient.impl.ClientBuilderBase;
+
+/**
+ * Entry point for building PostgreSQL clients.
+ */
+@VertxGen
+public interface PgBuilder {
+
+  /**
+   * Build a pool with the specified {@code block} argument.
+   * The {@code block} argument is usually a lambda that configures the provided builder
+   * <p>
+   * Example usage: {@code Pool pool = PgBuilder.pool(builder -> builder.connectingTo(connectOptions));}
+   *
+   * @return the pool as configured by the code {@code block}
+   */
+  static Pool pool(Handler<ClientBuilder<Pool>> block) {
+    ClientBuilder<Pool> builder = pool();
+    block.handle(builder);
+    return builder.build();
+  }
+
+  /**
+   * Provide a builder for PostgreSQL pool of connections
+   * <p>
+   * Example usage: {@code Pool pool = PgBuilder.pool().connectingTo(connectOptions).build()}
+   */
+  static ClientBuilder<Pool> pool() {
+    return new ClientBuilderBase<Pool>(PgDriver.INSTANCE) {
+      @Override
+      public Pool build() {
+        PoolOptions options = poolOptions;
+        if (options == null) {
+          options = new PoolOptions();
+        }
+        return driver.createPool(vertx, database, options);
+      }
+    };
+  }
+
+  /**
+   * Build a client backed by a connection pool with the specified {@code block} argument.
+   * The {@code block} argument is usually a lambda that configures the provided builder
+   * <p>
+   * Example usage: {@code SqlClient client = PgBuilder.client(builder -> builder.connectingTo(connectOptions));}
+   *
+   * @return the client as configured by the code {@code block}
+   */
+  static SqlClient client(Handler<ClientBuilder<SqlClient>> handler) {
+    ClientBuilder<SqlClient> builder = client();
+    handler.handle(builder);
+    return builder.build();
+  }
+
+  /**
+   * Provide a builder for PostgreSQL client backed by a connection pool.
+   * <p>
+   * Example usage: {@code SqlClient client = PgBuilder.client().connectingTo(connectOptions).build()}
+   */
+  static ClientBuilder<SqlClient> client() {
+    return new ClientBuilderBase<SqlClient>(PgDriver.INSTANCE) {
+      @Override
+      public Pool build() {
+        PoolOptions options = poolOptions;
+        if (options != null) {
+          options = new PgPoolOptions(poolOptions).setPipelined(true);
+        } else {
+          options = new PoolOptions();
+        }
+        return driver.createPool(vertx, database, options);
+      }
+    };
+  }
+}

vertx-pg-client/src/main/java/io/vertx/pgclient/PgPool.java

@@ -41,6 +41,7 @@
  *
  * @author <a href="mailto:julien@julienviet.com">Julien Viet</a>
  */
+@Deprecated
 @VertxGen
 public interface PgPool extends Pool {
 

vertx-pg-client/src/main/java/io/vertx/pgclient/impl/PgPoolOptions.java

@@ -24,6 +24,9 @@ public PgPoolOptions(PoolOptions other) {
     super(other);
   }
 
+  public PgPoolOptions() {
+  }
+
   private boolean pipelined;
 
   public boolean isPipelined() {

vertx-pg-client/src/test/java/io/vertx/pgclient/CloseConnectionTest.java

@@ -7,6 +7,7 @@
 import io.vertx.ext.unit.Async;
 import io.vertx.ext.unit.TestContext;
 import io.vertx.pgclient.spi.PgDriver;
+import io.vertx.sqlclient.Pool;
 import io.vertx.sqlclient.PoolOptions;
 import io.vertx.sqlclient.ProxyServer;
 import io.vertx.sqlclient.spi.ConnectionFactory;
@@ -41,7 +42,10 @@ public void testCloseConnection(TestContext ctx) {
   @Test
   public void testClosePooledConnection(TestContext ctx) {
     testCloseConnection(ctx, () -> {
-      PgPool pool = PgPool.pool(vertx, options, new PoolOptions().setMaxSize(1));
+      Pool pool = PgBuilder.pool(builder -> builder
+        .config(new PoolOptions().setMaxSize(1))
+        .connectingTo(options)
+        .using(vertx));
       pool.getConnection().onComplete(ctx.asyncAssertSuccess(conn -> {
         conn.close(ctx.asyncAssertSuccess(v -> {
           pool.close(ctx.asyncAssertSuccess());
@@ -53,7 +57,10 @@ public void testClosePooledConnection(TestContext ctx) {
   @Test
   public void testCloseNetSocket(TestContext ctx) {
     testCloseConnection(ctx, () -> {
-      PgPool pool = PgPool.pool(vertx, options, new PoolOptions().setMaxSize(1));
+      Pool pool = PgBuilder.pool(builder -> builder
+        .config(new PoolOptions().setMaxSize(1))
+        .connectingTo(options)
+        .using(vertx));
       ConnectionFactory factory = PgDriver.INSTANCE.createConnectionFactory(vertx, options);
       pool.connectionProvider(factory::connect);
       pool.getConnection().onComplete(ctx.asyncAssertSuccess(conn -> {