add EntityManager.runWithConnection()/callWithConnection()

see jakartaee#432

api/src/main/java/jakarta/persistence/ConnectionConsumer.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2008, 2021 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ */
+
+// Contributors:
+//     Gavin King      - 3.2
+
+
+package jakarta.persistence;
+
+import java.sql.Connection;
+import java.sql.SQLException;
+
+/**
+ * An executable action which makes use of a {@linkplain Connection JDBC connection}.
+ *
+ * @see ConnectionFunction
+ * @see EntityManager#runWithConnection(ConnectionConsumer)
+ *
+ * @since 3.2
+ */
+@FunctionalInterface
+public interface ConnectionConsumer {
+	/**
+	 * Execute the action using the given connection.
+	 *
+	 * @param connection the connection to use
+	 *
+	 * @throws SQLException if a problem occurs calling JDBC
+	 */
+	void accept(Connection connection) throws SQLException;
+}

api/src/main/java/jakarta/persistence/ConnectionFunction.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2008, 2021 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ */
+
+// Contributors:
+//     Gavin King      - 3.2
+
+
+package jakarta.persistence;
+
+import java.sql.Connection;
+import java.sql.SQLException;
+
+/**
+ * A function which makes use of a {@linkplain Connection JDBC connection}
+ * to compute a result.
+ *
+ * @see ConnectionConsumer
+ * @see EntityManager#callWithConnection(ConnectionFunction)
+ *
+ * @since 3.2
+ */
+@FunctionalInterface
+public interface ConnectionFunction<T> {
+	/**
+	 * Compute a result using the given connection.
+	 *
+	 * @param connection the connection to use
+	 *
+	 * @return the result
+	 * 
+	 * @throws SQLException if a problem occurs calling JDBC
+	 */
+	T apply(Connection connection) throws SQLException;
+}

api/src/main/java/jakarta/persistence/EntityManager.java

@@ -11,6 +11,7 @@
  */
 
 // Contributors:
+//     Gavin King      - 3.2
 //     Linda DeMichiel - 2.1
 //     Linda DeMichiel - 2.0
 
@@ -894,4 +895,30 @@ public StoredProcedureQuery createStoredProcedureQuery(
      */
     public <T> List<EntityGraph<? super T>> getEntityGraphs(Class<T> entityClass);
 
+    /**
+     * Execute the given action using the {@link java.sql.Connection} underlying
+     * this <code>EntityManager</code>. If this <code>EntityManager</code> is
+     * associated with a transaction, the action is executed in the context of
+     * the transaction.
+     * @param action the action
+     * @throws PersistenceException wrapping the {@link java.sql.SQLException}
+     *         thrown by {@link ConnectionConsumer#accept}, if any
+     * @since 3.2
+     */
+    public void runWithConnection(ConnectionConsumer action);
+
+    /**
+     * Call the given function and return its result using the {@link java.sql.Connection}
+     * underlying this <code>EntityManager</code>. If this <code>EntityManager</code> is
+     * associated with a transaction, the function is executed in the context of the
+     * transaction.
+     * @param function the function
+     * @param <T> the type of result returned by the function
+     * @return the value returned by {@link ConnectionFunction#apply}.
+     * @throws PersistenceException wrapping the {@link java.sql.SQLException}
+     *         thrown by {@link ConnectionFunction#apply}, if any
+     * @since 3.2
+     */
+    public <T> T callWithConnection(ConnectionFunction<T> function);
+
 }

spec/src/main/asciidoc/appendixes.adoc

@@ -108,6 +108,8 @@ Added support for Java record types as embeddable classes
 
 Added `||` string concatenation operator
 
+Added _runWithConnection()_ and _callWithConnection()_ to _EntityManager_
+
 Added _getSingleResultOrNull()_ to _Query_, _TypedQuery_, _StoredProcedureQuery_
 
 Added _concat()_ overload accepting list of expressions to _CriteriaBuilder_