Implement Oracle generated keys retrieval (#1083)

* Initial version of OracleGeneratedKeysTest

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* Refactor commands

There were many duplicated fragments in commands.
Besides, prepared statements were not always prepared on a worker thread and SQL exception were sometimes unhandled.

This commit is a first attempt to minimize code duplication and blocking code / failure management issues.

Also, it fixes generated keys retrieval (see #1074).

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* OracleConnectOptions are not needed for query commands

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* OraclePreparedStatement is already unwrapped

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* Make QueryCommand#doExecute abstract

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* Simplified OracleCursorQueryCommand implementation

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* Removed ResultDecoder

It was not providing much and this will avoid creating an extra object for every query

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* Verify all generated keys retrieval methods

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* Move Oracle property kinds to OracleClient interface

The purpose is to have an API similar to the API of the Reactive MySQL client.

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* Document Oracle generated key retrieval

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

Author: tsegismont

vertx-oracle-client/src/main/asciidoc/index.adoc

@@ -113,6 +113,27 @@ You can configure the client to retry when a connection fails to be established.
 
 include::queries.adoc[leveloffset=1]
 
+== Retrieving generated key values
+
+When executing `INSERT` queries, you can retrieve the generated key values.
+
+The values are returned as a {@link io.vertx.sqlclient.Row} instance.
+This instance is accessible by invoking {@link io.vertx.sqlclient.SqlResult#property SqlResult.property(kind)} using the {@link io.vertx.oracleclient.OracleClient#GENERATED_KEYS} property kind.
+
+The key values can be retrieved by column name:
+
+[source,$lang]
+----
+{@link examples.OracleClientExamples#retrieveGeneratedKeyByName}
+----
+
+Or, they can be retrieved by column index:
+
+[source,$lang]
+----
+{@link examples.OracleClientExamples#retrieveGeneratedKeyByIndex}
+----
+
 include::connections.adoc[]
 
 include::transactions.adoc[]

vertx-oracle-client/src/main/java/examples/OracleClientExamples.java

@@ -13,10 +13,13 @@
 
 import io.vertx.core.Vertx;
 import io.vertx.core.buffer.Buffer;
+import io.vertx.core.json.JsonArray;
 import io.vertx.core.json.JsonObject;
 import io.vertx.docgen.Source;
+import io.vertx.oracleclient.OracleClient;
 import io.vertx.oracleclient.OracleConnectOptions;
 import io.vertx.oracleclient.OraclePool;
+import io.vertx.oracleclient.OraclePrepareOptions;
 import io.vertx.sqlclient.*;
 import io.vertx.sqlclient.data.Numeric;
 
@@ -392,4 +395,38 @@ public void storedProcedureExample(SqlClient client) {
       }
     });
   }
+
+  public void retrieveGeneratedKeyByName(SqlClient client) {
+    String sql = "INSERT INTO EntityWithIdentity (name, position) VALUES (?, ?)";
+
+    // Retrieve generated key column value by name
+    OraclePrepareOptions options = new OraclePrepareOptions()
+      .setAutoGeneratedKeysIndexes(new JsonArray().add("ID"));
+
+    client.preparedQuery(sql, options).execute(Tuple.of("john", 3), ar -> {
+      if (ar.succeeded()) {
+        RowSet<Row> result = ar.result();
+
+        Row generated = result.property(OracleClient.GENERATED_KEYS);
+        Long id = generated.getLong("ID");
+      }
+    });
+  }
+
+  public void retrieveGeneratedKeyByIndex(SqlClient client) {
+    String sql = "INSERT INTO EntityWithIdentity (name, position) VALUES (?, ?)";
+
+    // Retrieve generated key column value by index
+    OraclePrepareOptions options = new OraclePrepareOptions()
+      .setAutoGeneratedKeysIndexes(new JsonArray().add("1"));
+
+    client.preparedQuery(sql, options).execute(Tuple.of("john", 3), ar -> {
+      if (ar.succeeded()) {
+        RowSet<Row> result = ar.result();
+
+        Row generated = result.property(OracleClient.GENERATED_KEYS);
+        Long id = generated.getLong("ID");
+      }
+    });
+  }
 }

vertx-oracle-client/src/main/java/io/vertx/oracleclient/OracleClient.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2011-2021 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 io.vertx.oracleclient;
+
+import io.vertx.codegen.annotations.VertxGen;
+import io.vertx.sqlclient.PropertyKind;
+import io.vertx.sqlclient.Row;
+
+/**
+ * An interface to define Oracle specific constants or behaviors.
+ */
+@VertxGen
+public interface OracleClient {
+
+  /**
+   * The property to be used to retrieve the generated keys
+   */
+  PropertyKind<Row> GENERATED_KEYS = PropertyKind.create("generated-keys", Row.class);
+
+  /**
+   * The property to be used to retrieve the output of the callable statement
+   */
+  PropertyKind<Boolean> OUTPUT = PropertyKind.create("callable-statement-output", Boolean.class);
+}

vertx-oracle-client/src/main/java/io/vertx/oracleclient/OraclePool.java

@@ -18,8 +18,6 @@
 import io.vertx.oracleclient.impl.OraclePoolImpl;
 import io.vertx.sqlclient.Pool;
 import io.vertx.sqlclient.PoolOptions;
-import io.vertx.sqlclient.PropertyKind;
-import io.vertx.sqlclient.Row;
 import io.vertx.sqlclient.impl.tracing.QueryTracer;
 
 /**
@@ -28,16 +26,6 @@
 @VertxGen
 public interface OraclePool extends Pool {
 
-  /**
-   * The property to be used to retrieve the generated keys
-   */
-  PropertyKind<Row> GENERATED_KEYS = PropertyKind.create("generated-keys", Row.class);
-
-  /**
-   * The property to be used to retrieve the output of the callable statement
-   */
-  PropertyKind<Boolean> OUTPUT = PropertyKind.create("callable-statement-output", Boolean.class);
-
   static OraclePool pool(OracleConnectOptions connectOptions, PoolOptions poolOptions) {
     if (Vertx.currentContext() != null) {
       throw new IllegalStateException(

vertx-oracle-client/src/main/java/io/vertx/oracleclient/impl/CommandHandler.java

@@ -104,7 +104,7 @@ private Future<Integer> handle(PingCommand ping) {
 
   @SuppressWarnings({ "unchecked", "rawtypes" })
   private <R> Future<Boolean> handle(io.vertx.sqlclient.impl.command.SimpleQueryCommand command) {
-    QueryCommand<?, R> action = new SimpleQueryCommand<>(options, command.sql(), command.collector());
+    QueryCommand<?, R> action = new SimpleQueryCommand<>(command.sql(), command.collector());
     return handle(action, command.resultHandler());
   }
 
@@ -124,15 +124,15 @@ private <R> Future<Boolean> handle(QueryCommand<?, R> action, QueryResultHandler
 
   private <R> Future<Boolean> handle(ExtendedQueryCommand<R> command) {
     if (command.cursorId() != null) {
-      QueryCommand<?, R> cmd = new OracleCursorQueryCommand<>(options, command, command.params());
+      QueryCommand<?, R> cmd = new OracleCursorQueryCommand<>(command, command.params());
       return cmd.execute(connection, context)
         .map(false);
     }
 
     QueryCommand<?, R> action =
       command.isBatch() ?
-        new OraclePreparedBatch<>(options, command, command.collector(), command.paramsList())
-        : new OraclePreparedQuery<>(options, command, command.collector(), command.params());
+        new OraclePreparedBatch<>(command, command.collector(), command.paramsList())
+        : new OraclePreparedQuery<>(command, command.collector(), command.params());
 
     return handle(action, command.resultHandler());
   }

vertx-oracle-client/src/main/java/io/vertx/oracleclient/impl/Helper.java

@@ -14,9 +14,12 @@
 import io.vertx.core.Promise;
 import io.vertx.core.VertxException;
 import io.vertx.core.impl.ContextInternal;
+import io.vertx.sqlclient.Tuple;
 import oracle.jdbc.OraclePreparedStatement;
 
+import java.math.BigDecimal;
 import java.sql.*;
+import java.time.ZoneOffset;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.CompletionStage;
@@ -27,20 +30,11 @@
 
 public class Helper {
 
-  public static <T> Future<T> completeOrFail(ThrowingSupplier<T> supplier) {
-    try {
-      return Future.succeededFuture(supplier.getOrThrow());
-    } catch (SQLException throwables) {
-      return Future.failedFuture(throwables);
-    }
-  }
-
-  public static void closeQuietly(Statement ps) {
-    if (ps != null) {
+  public static void closeQuietly(AutoCloseable autoCloseable) {
+    if (autoCloseable != null) {
       try {
-        ps.close();
-      } catch (SQLException throwables) {
-        // ignore me.
+        autoCloseable.close();
+      } catch (Exception ignore) {
       }
     }
   }
@@ -57,22 +51,6 @@ public static <T> Future<T> contextualize(CompletionStage<T> stage, ContextInter
     return future.future();
   }
 
-  /**
-   * Returns a {@code PreparedStatement}
-   * {@linkplain Wrapper#unwrap(Class) unwrapped} as an
-   * {@code OraclePreparedStatement}, or throws an {@code R2dbcException} if it
-   * does not wrap or implement the Oracle JDBC interface.
-   *
-   * @param preparedStatement A JDBC prepared statement
-   * @return An Oracle JDBC prepared statement
-   * @throws VertxException If an Oracle JDBC prepared statement is not wrapped.
-   */
-  public static OraclePreparedStatement unwrapOraclePreparedStatement(
-    PreparedStatement preparedStatement) {
-    return getOrHandleSQLException(() ->
-      preparedStatement.unwrap(OraclePreparedStatement.class));
-  }
-
   /**
    * Returns the specified {@code supplier}'s output, or throws a
    * {@link VertxException} if the function throws a {@link SQLException}. This
@@ -174,6 +152,106 @@ public void onComplete() {
     return promise.future();
   }
 
+  public static Object convertSqlValue(Object value) throws SQLException {
+    if (value == null) {
+      return null;
+    }
+
+    // valid json types are just returned as is
+    if (value instanceof Boolean || value instanceof String || value instanceof byte[]) {
+      return value;
+    }
+
+    // numeric values
+    if (value instanceof Number) {
+      if (value instanceof BigDecimal) {
+        BigDecimal d = (BigDecimal) value;
+        if (d.scale() == 0) {
+          return ((BigDecimal) value).toBigInteger();
+        } else {
+          // we might loose precision here
+          return ((BigDecimal) value).doubleValue();
+        }
+      }
+
+      return value;
+    }
+
+    // JDBC temporal values
+
+    if (value instanceof Time) {
+      return ((Time) value).toLocalTime();
+    }
+
+    if (value instanceof Date) {
+      return ((Date) value).toLocalDate();
+    }
+
+    if (value instanceof Timestamp) {
+      return ((Timestamp) value).toInstant().atOffset(ZoneOffset.UTC);
+    }
+
+    // large objects
+    if (value instanceof Clob) {
+      Clob c = (Clob) value;
+      try {
+        // result might be truncated due to downcasting to int
+        return c.getSubString(1, (int) c.length());
+      } finally {
+        try {
+          c.free();
+        } catch (AbstractMethodError | SQLFeatureNotSupportedException e) {
+          // ignore since it is an optional feature since 1.6 and non existing before 1.6
+        }
+      }
+    }
+
+    if (value instanceof Blob) {
+      Blob b = (Blob) value;
+      try {
+        // result might be truncated due to downcasting to int
+        return b.getBytes(1, (int) b.length());
+      } finally {
+        try {
+          b.free();
+        } catch (AbstractMethodError | SQLFeatureNotSupportedException e) {
+          // ignore since it is an optional feature since 1.6 and non existing before 1.6
+        }
+      }
+    }
+
+    // arrays
+    if (value instanceof Array) {
+      Array a = (Array) value;
+      try {
+        Object arr = a.getArray();
+        if (arr != null) {
+          int len = java.lang.reflect.Array.getLength(arr);
+          Object[] castedArray = new Object[len];
+          for (int i = 0; i < len; i++) {
+            castedArray[i] = convertSqlValue(java.lang.reflect.Array.get(arr, i));
+          }
+          return castedArray;
+        }
+      } finally {
+        a.free();
+      }
+    }
+
+    // RowId
+    if (value instanceof RowId) {
+      return ((RowId) value).getBytes();
+    }
+
+    // Struct
+    if (value instanceof Struct) {
+      return Tuple.of(((Struct) value).getAttributes());
+    }
+
+    // fallback to String
+    return value.toString();
+  }
+
   /**
    * <p>
    * Function type that returns a value or throws a {@link SQLException}. This