From 60dbac37f6c220283cc430655792a6c063119643 Mon Sep 17 00:00:00 2001
From: fhanik <fhanik@13f79535-47bb-0310-9956-ffa450edef68>
Date: Tue, 14 Jul 2009 15:22:05 +0000
Subject: [PATCH] More doco

git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@793937 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/tomcat/jdbc/pool/interceptor/ConnectionState.java | 9 ++++++++-
 .../apache/tomcat/jdbc/pool/interceptor/ResetAbandonedTimer.java | 5 ++++-
 .../apache/tomcat/jdbc/pool/interceptor/StatementFinalizer.java  | 6 ++++--
 3 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/ConnectionState.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/ConnectionState.java
index 991bf9418..c097e5484 100644
--- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/ConnectionState.java
+++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/ConnectionState.java
@@ -28,7 +28,14 @@ import org.apache.tomcat.jdbc.pool.PoolConfiguration;
 import org.apache.tomcat.jdbc.pool.PooledConnection;
 
 /**
- * Interceptor that keep track of connection state to avoid roundtrips to the database
+ * Interceptor that keep track of connection state to avoid roundtrips to the database.
+ * The {@link org.apache.tomcat.jdbc.pool.ConnectionPool} is optimized to do as little work as possible.
+ * The pool itself doesn't remember settings like {@link java.sql.Connection#setAutoCommit(boolean)}, 
+ * {@link java.sql.Connection#setReadOnly(boolean)}, {@link java.sql.Connection#setCatalog(String)} or
+ * {@link java.sql.Connection#setTransactionIsolation(int)}. It relies on the application to remember how and when 
+ * these settings have been applied.
+ * In the cases where the application code doesn't know or want to keep track of the state, this interceptor helps cache the 
+ * state, and it also avoids roundtrips to the database asking for it.
  * @author fhanik
  *
  */
diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/ResetAbandonedTimer.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/ResetAbandonedTimer.java
index fd0f56759..9e5ec0a08 100644
--- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/ResetAbandonedTimer.java
+++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/ResetAbandonedTimer.java
@@ -25,7 +25,10 @@ import org.apache.tomcat.jdbc.pool.ProxyConnection;
 
 /**
  * Class that resets the abandoned timer on any activity on the 
- * Connection or any successful query executions
+ * Connection or any successful query executions.
+ * This interceptor is useful for when you have a {@link org.apache.tomcat.jdbc.pool.PoolConfiguration#setRemoveAbandonedTimeout(int)}
+ * that is fairly low, and you want to reset the abandoned time each time any operation on the connection is performed
+ * This is useful for batch processing programs that use connections for extensive amount of times.
  * @author fhanik
  *
  */
diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/StatementFinalizer.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/StatementFinalizer.java
index d9473530b..c643e5790 100644
--- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/StatementFinalizer.java
+++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/StatementFinalizer.java
@@ -26,7 +26,8 @@ import org.apache.juli.logging.LogFactory;
 import org.apache.tomcat.jdbc.pool.ConnectionPool;
 import org.apache.tomcat.jdbc.pool.PooledConnection;
 /**
- * Keeps track of statements associated with a connection and invokes close upon connection.close()
+ * Keeps track of statements associated with a connection and invokes close upon {@link java.sql.Connection#close()}
+ * Useful for applications that dont close the associated statements after being done with a connection.
  * @author fhanik
  *
  */
@@ -39,7 +40,8 @@ public class StatementFinalizer extends AbstractCreateStatementInterceptor {
     public Object createStatement(Object proxy, Method method, Object[] args, Object statement, long time) {
         // TODO Auto-generated method stub
         try {
-            statements.add(new WeakReference<Statement>((Statement)statement));
+            if (statement instanceof Statement)
+                statements.add(new WeakReference<Statement>((Statement)statement));
         }catch (ClassCastException x) {
             //ignore this one
         }
-- 
2.11.0