WL#12246, DevAPI: Prepared statement support.

Author: fjssilva

CHANGES

@@ -3,6 +3,8 @@
 
 Version 8.0.16
 
+  - WL#12246, DevAPI: Prepared statement support.
+
   - WL#10839, Adjust c/J tests to the new "ON" default for explicit_defaults_for_timestamp.
 
   - Fix for Bug#29329326, PLEASE AVOID SHOW PROCESSLIST IF POSSIBLE.

src/generated/java/com/mysql/cj/x/protobuf/Mysqlx.java

@@ -31,7 +31,7 @@
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
 // source: mysqlx.proto
-@SuppressWarnings({ "unchecked", "synthetic-access", "cast" })
+@SuppressWarnings({ "cast" })
 
 public final class Mysqlx {
   private Mysqlx() {}

src/generated/java/com/mysql/cj/x/protobuf/MysqlxConnection.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify it under
  * the terms of the GNU General Public License, version 2.0, as published by the
@@ -31,7 +31,7 @@
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
 // source: mysqlx_connection.proto
-@SuppressWarnings({ "unchecked", "synthetic-access", "cast", "deprecation" })
+@SuppressWarnings({ "cast", "deprecation" })
 
 public final class MysqlxConnection {
   private MysqlxConnection() {}

src/generated/java/com/mysql/cj/x/protobuf/MysqlxCrud.java

@@ -31,7 +31,7 @@
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
 // source: mysqlx_crud.proto
-@SuppressWarnings({ "unchecked", "synthetic-access", "cast", "deprecation" })
+@SuppressWarnings({ "deprecation", "cast" })
 
 public final class MysqlxCrud {
   private MysqlxCrud() {}

src/generated/java/com/mysql/cj/x/protobuf/MysqlxCursor.java

@@ -30,7 +30,7 @@
 package com.mysql.cj.x.protobuf;
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
-// source: mysqlx_crud.proto
+// source: mysqlx_cursor.proto
 @SuppressWarnings({ "cast", "deprecation" })
 
 public final class MysqlxCursor {

src/generated/java/com/mysql/cj/x/protobuf/MysqlxDatatypes.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify it under
  * the terms of the GNU General Public License, version 2.0, as published by the
@@ -31,7 +31,7 @@
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
 // source: mysqlx_datatypes.proto
-@SuppressWarnings({ "unchecked", "synthetic-access", "cast" })
+@SuppressWarnings({ "cast" })
 
 public final class MysqlxDatatypes {
   private MysqlxDatatypes() {}

src/generated/java/com/mysql/cj/x/protobuf/MysqlxExpect.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify it under
  * the terms of the GNU General Public License, version 2.0, as published by the
@@ -31,7 +31,7 @@
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
 // source: mysqlx_expect.proto
-@SuppressWarnings({ "unchecked", "synthetic-access", "cast" })
+@SuppressWarnings({ "cast" })
 
 public final class MysqlxExpect {
   private MysqlxExpect() {}

src/generated/java/com/mysql/cj/x/protobuf/MysqlxExpr.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify it under
  * the terms of the GNU General Public License, version 2.0, as published by the
@@ -31,7 +31,7 @@
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
 // source: mysqlx_expr.proto
-@SuppressWarnings({ "unchecked", "synthetic-access", "cast", "deprecation" })
+@SuppressWarnings({ "cast", "deprecation" })
 
 public final class MysqlxExpr {
   private MysqlxExpr() {}

src/generated/java/com/mysql/cj/x/protobuf/MysqlxNotice.java

@@ -31,7 +31,7 @@
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
 // source: mysqlx_notice.proto
-@SuppressWarnings({ "unchecked", "synthetic-access", "cast", "deprecation" })
+@SuppressWarnings({ "cast", "deprecation" })
 
 public final class MysqlxNotice {
   private MysqlxNotice() {}

src/generated/java/com/mysql/cj/x/protobuf/MysqlxPrepare.java

@@ -30,7 +30,7 @@
 package com.mysql.cj.x.protobuf;
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
-// source: mysqlx_notice.proto
+// source: mysqlx_prepare.proto
 @SuppressWarnings({ "cast", "deprecation" })
 
 public final class MysqlxPrepare {

src/generated/java/com/mysql/cj/x/protobuf/MysqlxResultset.java

@@ -31,7 +31,7 @@
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
 // source: mysqlx_resultset.proto
-@SuppressWarnings({ "unchecked", "synthetic-access", "cast" })
+@SuppressWarnings({ "cast" })
 
 public final class MysqlxResultset {
   private MysqlxResultset() {}

src/generated/java/com/mysql/cj/x/protobuf/MysqlxSession.java

@@ -31,7 +31,7 @@
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
 // source: mysqlx_session.proto
-@SuppressWarnings({ "unchecked", "synthetic-access", "cast" })
+@SuppressWarnings({ "cast" })
 
 public final class MysqlxSession {
   private MysqlxSession() {}

src/generated/java/com/mysql/cj/x/protobuf/MysqlxSql.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify it under
  * the terms of the GNU General Public License, version 2.0, as published by the
@@ -31,7 +31,7 @@
 
 // Generated by the protocol buffer compiler.  DO NOT EDIT!
 // source: mysqlx_sql.proto
-@SuppressWarnings({ "unchecked", "synthetic-access", "cast", "deprecation" })
+@SuppressWarnings({ "cast", "deprecation" })
 
 public final class MysqlxSql {
   private MysqlxSql() {}

src/main/core-api/java/com/mysql/cj/protocol/ServerSession.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify it under
  * the terms of the GNU General Public License, version 2.0, as published by the
@@ -37,7 +37,6 @@
 /**
  * Keeps the effective states of server/session variables,
  * contains methods for initial retrieving of these states and for their actualization.
- * 
  */
 public interface ServerSession {
 

src/main/core-api/java/com/mysql/cj/util/SequentialIdLease.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, version 2.0, as published by the
+ * Free Software Foundation.
+ *
+ * This program is also distributed with certain software (including but not
+ * limited to OpenSSL) that is licensed under separate terms, as designated in a
+ * particular file or component or in included license documentation. The
+ * authors of MySQL hereby grant you an additional permission to link the
+ * program and your derivative works with the separately licensed software that
+ * they have included with MySQL.
+ *
+ * Without limiting anything contained in the foregoing, this file, which is
+ * part of MySQL Connector/J, is also subject to the Universal FOSS Exception,
+ * version 1.0, a copy of which can be found at
+ * http://oss.oracle.com/licenses/universal-foss-exception.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0,
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
+ */
+
+package com.mysql.cj.util;
+
+import java.util.Iterator;
+import java.util.Set;
+import java.util.TreeSet;
+
+public class SequentialIdLease {
+    private Set<Integer> sequentialIdsLease = new TreeSet<>();
+
+    /**
+     * Finds and allocates the first available sequential id.
+     * 
+     * @return the next free sequential id.
+     */
+    public int allocateSequentialId() {
+        int nextSequentialId = 0;
+        for (Iterator<Integer> it = this.sequentialIdsLease.iterator(); it.hasNext() && nextSequentialId + 1 == it.next(); nextSequentialId++) {
+            // Find the first free sequential id.
+        }
+        this.sequentialIdsLease.add(++nextSequentialId);
+        return nextSequentialId;
+    }
+
+    /**
+     * Frees the given sequential id so that it can be reused.
+     * 
+     * @param sequentialId
+     *            the sequential id to release
+     */
+    public void releaseSequentialId(int sequentialId) {
+        this.sequentialIdsLease.remove(sequentialId);
+    }
+}

src/main/core-impl/java/com/mysql/cj/CoreSession.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify it under
  * the terms of the GNU General Public License, version 2.0, as published by the
@@ -35,6 +35,7 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Function;
 import java.util.function.Predicate;
+import java.util.function.Supplier;
 import java.util.stream.Collector;
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
@@ -155,8 +156,12 @@ public <M extends Message> MessageBuilder<M> getMessageBuilder() {
     }
 
     public <QR extends QueryResult> QR sendMessage(Message message) {
+        return sendMessage(message, this.protocol::readQueryResult);
+    }
+
+    public <R> R sendMessage(Message message, Supplier<R> readResult) {
         this.protocol.send(message, 0);
-        return this.protocol.readQueryResult();
+        return readResult.get();
     }
 
     public <QR extends QueryResult> CompletableFuture<QR> asyncSendMessage(Message message) {

src/main/core-impl/java/com/mysql/cj/MysqlxSession.java

@@ -47,8 +47,11 @@
 import com.mysql.cj.protocol.x.StatementExecuteOkBuilder;
 import com.mysql.cj.protocol.x.XMessageBuilder;
 import com.mysql.cj.protocol.x.XProtocol;
+import com.mysql.cj.protocol.x.XProtocolError;
 import com.mysql.cj.result.RowList;
 import com.mysql.cj.xdevapi.FilterParams;
+import com.mysql.cj.xdevapi.FilterableStatement;
+import com.mysql.cj.xdevapi.PreparableStatement;
 import com.mysql.cj.xdevapi.SqlDataResult;
 import com.mysql.cj.xdevapi.SqlResult;
 import com.mysql.cj.xdevapi.SqlResultImpl;
@@ -90,6 +93,67 @@ public void quit() {
         }
     }
 
+    /**
+     * Consume an OK packet from the underlying protocol.
+     * 
+     * @return <code>null</code>
+     */
+    public Void readOk() {
+        ((XProtocol) this.protocol).readOk();
+        return null;
+    }
+
+    /**
+     * Check if current session is using a MySQL server that supports prepared statements.
+     * 
+     * @return
+     *         {@code true} if the MySQL server in use supports prepared statements
+     */
+    public boolean supportsPreparedStatements() {
+        return ((XProtocol) this.protocol).supportsPreparedStatements();
+    }
+
+    /**
+     * Check if enough statements were executed in the underlying MySQL server so that another prepare statement attempt should be done.
+     * 
+     * @return
+     *         {@code true} if enough executions have been done since last time a prepared statement failed to be prepared
+     */
+    public boolean readyForPreparingStatements() {
+        return ((XProtocol) this.protocol).readyForPreparingStatements();
+    }
+
+    /**
+     * Return an id to be used as a client-managed prepared statement id.
+     * 
+     * @return a new identifier to be used as prepared statement id
+     */
+    public int getNewPreparedStatementId(PreparableStatement<?> preparableStatement) {
+        return ((XProtocol) this.protocol).getNewPreparedStatementId(preparableStatement);
+    }
+
+    /**
+     * Free a prepared statement id so that it can be reused.
+     * 
+     * @param preparedStatementId
+     *            the prepared statement id to release
+     */
+    public void freePreparedStatementId(int preparedStatementId) {
+        ((XProtocol) this.protocol).freePreparedStatementId(preparedStatementId);
+    }
+
+    /**
+     * Propagate to the underlying protocol instance that preparing a statement on the connected server failed.
+     * 
+     * @param preparedStatementId
+     *            the id of the prepared statement that failed to be prepared
+     * @return
+     *         {@code true} if the exception was properly handled
+     */
+    public boolean failedPreparingStatement(int preparedStatementId, XProtocolError e) {
+        return ((XProtocol) this.protocol).failedPreparingStatement(preparedStatementId, e);
+    }
+
     public <T extends ResultStreamer> T find(FilterParams filterParams,
             Function<ColumnDefinition, BiFunction<RowList, Supplier<StatementExecuteOk>, T>> resultCtor) {
         this.protocol.send(((XMessageBuilder) this.messageBuilder).buildFind(filterParams), 0);
@@ -99,6 +163,27 @@ public <T extends ResultStreamer> T find(FilterParams filterParams,
         return res;
     }
 
+    /**
+     * Execute a previously prepared find statement using the given arguments.
+     * 
+     * @param preparedStatementId
+     *            the prepared statement id to execute. This statement must be previously prepared
+     * @param filterParams
+     *            the {@link FilterableStatement} params that contain the arguments for the previously-defined placeholders
+     * @param resultCtor
+     *            a constructor that builds the results.
+     * @return
+     *         the result from the given constructor
+     */
+    public <T extends ResultStreamer> T executePreparedFind(int preparedStatementId, FilterParams filterParams,
+            Function<ColumnDefinition, BiFunction<RowList, Supplier<StatementExecuteOk>, T>> resultCtor) {
+        this.protocol.send(((XMessageBuilder) this.messageBuilder).buildPrepareExecute(preparedStatementId, filterParams), 0);
+        ColumnDefinition metadata = this.protocol.readMetadata();
+        T res = resultCtor.apply(metadata).apply(((XProtocol) this.protocol).getRowInputStream(metadata), this.protocol::readQueryResult);
+        this.protocol.setCurrentResultStreamer(res);
+        return res;
+    }
+
     public <RES_T> CompletableFuture<RES_T> asyncFind(FilterParams filterParams,
             Function<ColumnDefinition, BiFunction<RowList, Supplier<StatementExecuteOk>, RES_T>> resultCtor) {
         CompletableFuture<RES_T> f = new CompletableFuture<>();
@@ -109,6 +194,16 @@ public <RES_T> CompletableFuture<RES_T> asyncFind(FilterParams filterParams,
 
     public SqlResult executeSql(String sql, List<Object> args) {
         this.protocol.send(this.messageBuilder.buildSqlStatement(sql, args), 0);
+        return executeSqlProcessResult();
+    }
+
+    /**
+     * Process the response messages from a <i>StmtExecute</i> request.
+     * 
+     * @return
+     *         an {@link SqlResult} with the returned rows.
+     */
+    private SqlResult executeSqlProcessResult() {
         boolean readLastResult[] = new boolean[1];
         Supplier<StatementExecuteOk> okReader = () -> {
             if (readLastResult[0]) {
@@ -145,5 +240,4 @@ public CompletableFuture<SqlResult> asyncExecuteSql(String sql, List<Object> arg
     public boolean isClosed() {
         return !((XProtocol) this.protocol).isOpen();
     }
-
 }