[#5377] Renamed ThreadLocalTransactionalXX to ContextTransactionalXX

jOOQ/src/main/java/org/jooq/ContextTransactionalCallable.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2009-2016, Data Geekery GmbH (http://www.datageekery.com)
+ * All rights reserved.
+ *
+ * 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.
+ *
+ * Other licenses:
+ * -----------------------------------------------------------------------------
+ * Commercial licenses for this work are available. These replace the above
+ * ASL 2.0 and offer limited warranties, support, maintenance, and commercial
+ * database integrations.
+ *
+ * For more information, please visit: http://www.jooq.org/licenses
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ */
+package org.jooq;
+
+import org.jooq.impl.ThreadLocalTransactionProvider;
+
+/**
+ * An <code>FunctionalInterface</code> that wraps transactional code.
+ * <p>
+ * This callable may depend on captured scope ("context") in order to discover a
+ * contextual {@link Configuration} to be used to create new SQL statements.
+ * Clients are responsible to implement such context state in appropriate
+ * {@link ConnectionProvider} and {@link TransactionProvider} implementations.
+ * <p>
+ * An out-of-the-box implementation for a fitting {@link TransactionProvider} is
+ * available through {@link ThreadLocalTransactionProvider}.
+ *
+ * @author Lukas Eder
+ */
+
+@FunctionalInterface
+
+public interface ContextTransactionalCallable<T> {
+
+    /**
+     * Run the transactional code.
+     * <p>
+     * If this method completes normally, and this is not a nested transaction,
+     * then the transaction will be committed. If this method completes with an
+     * exception, then the transaction is rolled back to the beginning of this
+     * <code>ContextTransactionalCallable</code>.
+     *
+     * @return The outcome of the transaction.
+     * @throws Exception Any exception that will cause a rollback of the code
+     *             contained in this transaction. If this is a nested
+     *             transaction, the rollback may be performed only to the state
+     *             before executing this
+     *             <code>ContextTransactionalCallable</code>.
+     */
+    T run() throws Exception;
+}

jOOQ/src/main/java/org/jooq/ContextTransactionalRunnable.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2009-2016, Data Geekery GmbH (http://www.datageekery.com)
+ * All rights reserved.
+ *
+ * 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.
+ *
+ * Other licenses:
+ * -----------------------------------------------------------------------------
+ * Commercial licenses for this work are available. These replace the above
+ * ASL 2.0 and offer limited warranties, support, maintenance, and commercial
+ * database integrations.
+ *
+ * For more information, please visit: http://www.jooq.org/licenses
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ */
+package org.jooq;
+
+import org.jooq.impl.ThreadLocalTransactionProvider;
+
+/**
+ * An <code>FunctionalInterface</code> that wraps transactional code.
+ * <p>
+ * This runnable may depend on captured scope ("context") in order to discover a
+ * contextual {@link Configuration} to be used to create new SQL statements.
+ * Clients are responsible to implement such context state in appropriate
+ * {@link ConnectionProvider} and {@link TransactionProvider} implementations.
+ * <p>
+ * An out-of-the-box implementation for a fitting {@link TransactionProvider} is
+ * available through {@link ThreadLocalTransactionProvider}.
+ *
+ * @author Lukas Eder
+ */
+
+@FunctionalInterface
+
+public interface ContextTransactionalRunnable {
+
+    /**
+     * Run the transactional code.
+     * <p>
+     * If this method completes normally, and this is not a nested transaction,
+     * then the transaction will be committed. If this method completes with an
+     * exception, then the transaction is rolled back to the beginning of this
+     * <code>ContextTransactionalRunnable</code>.
+     *
+     * @throws Exception Any exception that will cause a rollback of the code
+     *             contained in this transaction. If this is a nested
+     *             transaction, the rollback may be performed only to the state
+     *             before executing this
+     *             <code>ContextTransactionalRunnable</code>.
+     */
+    void run() throws Exception;
+}

jOOQ/src/main/java/org/jooq/DSLContext.java

@@ -273,44 +273,68 @@ public interface DSLContext extends Scope , AutoCloseable  {
      * <code>DSLContext</code>'s underlying {@link #configuration()}'s
      * {@link Configuration#transactionProvider()}, and return the
      * <code>transactional</code>'s outcome.
+     * <p>
+     * The argument transactional code should not capture any scope but derive
+     * its {@link Configuration} from the
+     * {@link TransactionalCallable#run(Configuration)} argument in order to
+     * create new statements.
      *
      * @param transactional The transactional code
      * @return The transactional outcome
      */
     <T> T transactionResult(TransactionalCallable<T> transactional);
 
     /**
-     * Run a {@link ThreadLocalTransactionalRunnable} in the context of this
+     * Run a {@link ContextTransactionalRunnable} in the context of this
      * <code>DSLContext</code>'s underlying {@link #configuration()}'s
-     * {@link ThreadLocalTransactionProvider}.
+     * {@link Configuration#transactionProvider()}, and return the
+     * <code>transactional</code>'s outcome.
+     * <p>
+     * The argument transactional code may capture scope to derive its
+     * {@link Configuration} from the "context" in order to create new
+     * statements. This context can be provided, for instance, by
+     * {@link ThreadLocalTransactionProvider} automatically.
      *
      * @param transactional The transactional code
+     * @return The transactional outcome
      * @throws ConfigurationException if the underlying
-     *             {@link Configuration#transactionProvider()} is not a
-     *             {@link ThreadLocalTransactionProvider}.
+     *             {@link Configuration#transactionProvider()} is not able to
+     *             provide context (i.e. currently, it is not a
+     *             {@link ThreadLocalTransactionProvider}).
      */
-    <T> T transactionResult(ThreadLocalTransactionalCallable<T> transactional) throws ConfigurationException;
+    <T> T transactionResult(ContextTransactionalCallable<T> transactional) throws ConfigurationException;
 
     /**
      * Run a {@link TransactionalRunnable} in the context of this
      * <code>DSLContext</code>'s underlying {@link #configuration()}'s
      * {@link Configuration#transactionProvider()}.
+     * <p>
+     * The argument transactional code should not capture any scope but derive
+     * its {@link Configuration} from the
+     * {@link TransactionalCallable#run(Configuration)} argument in order to
+     * create new statements.
      *
      * @param transactional The transactional code
      */
     void transaction(TransactionalRunnable transactional);
 
     /**
-     * Run a {@link ThreadLocalTransactionalRunnable} in the context of this
+     * Run a {@link ContextTransactionalRunnable} in the context of this
      * <code>DSLContext</code>'s underlying {@link #configuration()}'s
-     * {@link ThreadLocalTransactionProvider}.
+     * {@link Configuration#transactionProvider()}.
+     * <p>
+     * The argument transactional code may capture scope to derive its
+     * {@link Configuration} from the "context" in order to create new
+     * statements. This context can be provided, for instance, by
+     * {@link ThreadLocalTransactionProvider} automatically.
      *
      * @param transactional The transactional code
      * @throws ConfigurationException if the underlying
-     *             {@link Configuration#transactionProvider()} is not a
-     *             {@link ThreadLocalTransactionProvider}.
+     *             {@link Configuration#transactionProvider()} is not able to
+     *             provide context (i.e. currently, it is not a
+     *             {@link ThreadLocalTransactionProvider}).
      */
-    void transaction(ThreadLocalTransactionalRunnable transactional) throws ConfigurationException;
+    void transaction(ContextTransactionalRunnable transactional) throws ConfigurationException;
 
 
 
@@ -327,7 +351,8 @@ public interface DSLContext extends Scope , AutoCloseable  {
      *
      * @param transactional The transactional code
      * @return The transactional outcome
-     * @throws ConfigurationException If this is run with a {@link ThreadLocalTransactionProvider}.
+     * @throws ConfigurationException If this is run with a
+     *             {@link ThreadLocalTransactionProvider}.
      */
     <T> CompletionStage<T> transactionResultAsync(TransactionalCallable<T> transactional) throws ConfigurationException;
 
@@ -343,7 +368,8 @@ public interface DSLContext extends Scope , AutoCloseable  {
      * {@link Configuration#executorProvider()}.
      *
      * @param transactional The transactional code
-     * @throws ConfigurationException If this is run with a {@link ThreadLocalTransactionProvider}.
+     * @throws ConfigurationException If this is run with a
+     *             {@link ThreadLocalTransactionProvider}.
      */
     CompletionStage<Void> transactionAsync(TransactionalRunnable transactional) throws ConfigurationException;
 
@@ -359,7 +385,8 @@ public interface DSLContext extends Scope , AutoCloseable  {
      *
      * @param transactional The transactional code
      * @return The transactional outcome
-     * @throws ConfigurationException If this is run with a {@link ThreadLocalTransactionProvider}.
+     * @throws ConfigurationException If this is run with a
+     *             {@link ThreadLocalTransactionProvider}.
      */
     <T> CompletionStage<T> transactionResultAsync(Executor executor, TransactionalCallable<T> transactional) throws ConfigurationException;
 
@@ -374,7 +401,8 @@ public interface DSLContext extends Scope , AutoCloseable  {
      * {@link Executor}.
      *
      * @param transactional The transactional code
-     * @throws ConfigurationException If this is run with a {@link ThreadLocalTransactionProvider}.
+     * @throws ConfigurationException If this is run with a
+     *             {@link ThreadLocalTransactionProvider}.
      */
     CompletionStage<Void> transactionAsync(Executor executor, TransactionalRunnable transactional) throws ConfigurationException;
 

jOOQ/src/main/java/org/jooq/TransactionalCallable.java

@@ -42,6 +42,13 @@
 
 /**
  * An <code>FunctionalInterface</code> that wraps transactional code.
+ * <p>
+ * Transactional code should not depend on any captured scope, but use the
+ * argument {@link Configuration} passed to the {@link #run(Configuration)}
+ * method to derive its transaction context.
+ * <p>
+ * If transactional code needs to depend on captured scope ("context"), then
+ * {@link ContextTransactionalCallable} is a better fit.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/TransactionalRunnable.java

@@ -42,6 +42,13 @@
 
 /**
  * An <code>FunctionalInterface</code> that wraps transactional code.
+ * <p>
+ * Transactional code should not depend on any captured scope, but use the
+ * argument {@link Configuration} passed to the {@link #run(Configuration)}
+ * method to derive its transaction context.
+ * <p>
+ * If transactional code needs to depend on captured scope ("context"), then
+ * {@link ContextTransactionalRunnable} is a better fit.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/impl/DefaultDSLContext.java

@@ -217,8 +217,8 @@
 import org.jooq.TableField;
 import org.jooq.TableLike;
 import org.jooq.TableRecord;
-import org.jooq.ThreadLocalTransactionalCallable;
-import org.jooq.ThreadLocalTransactionalRunnable;
+import org.jooq.ContextTransactionalCallable;
+import org.jooq.ContextTransactionalRunnable;
 import org.jooq.TransactionProvider;
 import org.jooq.TransactionalCallable;
 import org.jooq.TransactionalRunnable;
@@ -419,7 +419,7 @@ public InformationSchema informationSchema(Table<?>... tables) {
     // -------------------------------------------------------------------------
 
     @Override
-    public <T> T transactionResult(final ThreadLocalTransactionalCallable<T> transactional) {
+    public <T> T transactionResult(final ContextTransactionalCallable<T> transactional) {
         TransactionProvider tp = configuration().transactionProvider();
 
         if (!(tp instanceof ThreadLocalTransactionProvider))
@@ -507,8 +507,8 @@ private static <T> T transactionResult0(TransactionalCallable<T> transactional,
     }
 
     @Override
-    public void transaction(final ThreadLocalTransactionalRunnable transactional) {
-        transactionResult(new ThreadLocalTransactionalCallable<Void>() {
+    public void transaction(final ContextTransactionalRunnable transactional) {
+        transactionResult(new ContextTransactionalCallable<Void>() {
             @Override
             public Void run() throws Exception {
                 transactional.run();