From 033f4f346fb3a2c69bd1babbc1a2073021ec77f4 Mon Sep 17 00:00:00 2001
From: Lukas Eder <lukas.eder@gmail.com>
Date: Sun, 15 Jul 2012 16:00:09 +0200
Subject: [PATCH] [#1553] Add some Javadoc to document the difference between
 using a Factory with a Connection or with a DataSource - Added additional
 Javadoc to transaction handling delegate methods in FactoryOperations

---
 .../main/java/org/jooq/FactoryOperations.java | 116 +++++++++++++++++-
 1 file changed, 114 insertions(+), 2 deletions(-)

diff --git a/jOOQ/src/main/java/org/jooq/FactoryOperations.java b/jOOQ/src/main/java/org/jooq/FactoryOperations.java
index 2b57ab2a0e..5c173922d2 100644
--- a/jOOQ/src/main/java/org/jooq/FactoryOperations.java
+++ b/jOOQ/src/main/java/org/jooq/FactoryOperations.java
@@ -58,6 +58,8 @@ import java.sql.Statement;
 import java.util.Collection;
 import java.util.List;
 
+import javax.sql.DataSource;
+
 import org.jooq.conf.Settings;
 import org.jooq.conf.StatementType;
 import org.jooq.exception.DataAccessException;
@@ -1651,61 +1653,171 @@ public interface FactoryOperations extends Configuration {
 
     /**
      * Convenience method to access {@link Connection#getTransactionIsolation()}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     int getTransactionIsolation() throws DataAccessException;
 
     /**
-     * Convenience method to access {@link Connection#setTransactionIsolation(int)}
+     * Convenience method to access
+     * {@link Connection#setTransactionIsolation(int)}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     void setTransactionIsolation(int level) throws DataAccessException;
 
     /**
      * Convenience method to access {@link Connection#getHoldability()}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     int getHoldability() throws DataAccessException;
 
     /**
      * Convenience method to access {@link Connection#setHoldability(int)}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     void setHoldability(int holdability) throws DataAccessException;
 
     /**
      * Convenience method to access {@link Connection#getAutoCommit()}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     boolean getAutoCommit() throws DataAccessException;
 
     /**
      * Convenience method to access {@link Connection#setAutoCommit(boolean)}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     void setAutoCommit(boolean autoCommit) throws DataAccessException;
 
     /**
-     * Convenience method to access {@link Connection#releaseSavepoint(Savepoint)}
+     * Convenience method to access
+     * {@link Connection#releaseSavepoint(Savepoint)}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     void releaseSavepoint(Savepoint savepoint) throws DataAccessException;
 
     /**
      * Convenience method to access {@link Connection#setSavepoint(String)}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     Savepoint setSavepoint(String name) throws DataAccessException;
 
     /**
      * Convenience method to access {@link Connection#setSavepoint()}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     Savepoint setSavepoint() throws DataAccessException;
 
     /**
      * Convenience method to access {@link Connection#rollback(Savepoint)}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     void rollback(Savepoint savepoint) throws DataAccessException;
 
     /**
      * Convenience method to access {@link Connection#rollback()}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     void rollback() throws DataAccessException;
 
     /**
      * Convenience method to access {@link Connection#commit()}
+     * <p>
+     * Use this method only if you control the JDBC {@link Connection} wrapped
+     * by this {@link Configuration}, and if that connection manages the current
+     * transaction. If your transaction is operated on a distributed
+     * <code>javax.transaction.UserTransaction</code>, for instance, this method
+     * will not work.
+     *
+     * @see Configuration#setConnection(Connection)
+     * @see Configuration#setDataSource(DataSource)
      */
     void commit() throws DataAccessException;
 }