From 901f2fcec0841b897817bdc6d22b8327acb1bda5 Mon Sep 17 00:00:00 2001
From: fhanik <fhanik@13f79535-47bb-0310-9956-ffa450edef68>
Date: Tue, 14 Jul 2009 14:53:20 +0000
Subject: [PATCH] more javadoc

git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@793919 13f79535-47bb-0310-9956-ffa450edef68
---
 modules/jdbc-pool/.classpath                       |  1 +
 .../AbstractCreateStatementInterceptor.java        | 34 +++++++++++++---
 .../jdbc/pool/interceptor/AbstractQueryReport.java | 46 ++++++++++++----------
 .../apache/tomcat/jdbc/test/DefaultTestCase.java   |  6 +--
 4 files changed, 55 insertions(+), 32 deletions(-)

diff --git a/modules/jdbc-pool/.classpath b/modules/jdbc-pool/.classpath
index 52761df18..f356401b8 100644
--- a/modules/jdbc-pool/.classpath
+++ b/modules/jdbc-pool/.classpath
@@ -8,5 +8,6 @@
 	<classpathentry kind="lib" path="includes/mysql-connector-java-5.1.7/mysql-connector-java-5.1.7-bin.jar"/>
 	<classpathentry kind="lib" path="includes/db-derby-10.5.1.1-bin/lib/derby.jar"/>
 	<classpathentry kind="lib" path="includes/h2/bin/h2-1.1.115.jar"/>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
 	<classpathentry kind="output" path="bin"/>
 </classpath>
diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractCreateStatementInterceptor.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractCreateStatementInterceptor.java
index 72d16e4d1..fd4d8a437 100644
--- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractCreateStatementInterceptor.java
+++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractCreateStatementInterceptor.java
@@ -23,6 +23,9 @@ import org.apache.tomcat.jdbc.pool.JdbcInterceptor;
 import org.apache.tomcat.jdbc.pool.PooledConnection;
 
 /**
+ * Abstraction interceptor. This component intercepts all calls to create some type of SQL statement.
+ * By extending this class, one can intercept queries and update statements by overriding the {@link #createStatement(Object, Method, Object[], Object, long)}
+ * method.
  * @author Filip Hanik
  * @version 1.0
  */
@@ -34,6 +37,9 @@ public abstract class  AbstractCreateStatementInterceptor extends JdbcIntercepto
         super();
     }
     
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
         if (compare(CLOSE_VAL,method)) {
@@ -54,18 +60,30 @@ public abstract class  AbstractCreateStatementInterceptor extends JdbcIntercepto
     }
     
     /**
-     * This method should return a wrapper object around a
+     * This method will be invoked after a successful statement creation. This method can choose to return a wrapper
+     * around the statement or return the statement itself.
+     * If this method returns a wrapper then it should return a wrapper object that implements one of the following interfaces.
      * {@link java.sql.Statement}, {@link java.sql.PreparedStatement} or {@link java.sql.CallableStatement}
-     * @param proxy
-     * @param method
-     * @param args
-     * @param statement
+     * @param proxy the actual proxy object
+     * @param method the method that was called. It will be one of the methods defined in {@link #statements}
+     * @param args the arguments to the method
+     * @param statement the statement that the underlying connection created
      * @return a {@link java.sql.Statement} object
      */
     public abstract Object createStatement(Object proxy, Method method, Object[] args, Object statement, long time);
     
+    /**
+     * Method invoked when the operation {@link java.sql.Connection#close()} is invoked. 
+     */
     public abstract void closeInvoked();
 
+    /**
+     * Returns true if the method that is being invoked matches one of the method names passed in
+     * @param names list of method names that we want to intercept
+     * @param method the method being invoked on the proxy
+     * @param process boolean result used for recursion
+     * @return returns true if the method name matched
+     */
     protected boolean process(String[] names, Method method, boolean process) {
         final String name = method.getName();
         for (int i=0; (!process) && i<names.length; i++) {
@@ -74,7 +92,11 @@ public abstract class  AbstractCreateStatementInterceptor extends JdbcIntercepto
         return process;
     }
     
+    /**
+     * no-op for this interceptor. no state is stored.
+     */
+    @Override
     public void reset(ConnectionPool parent, PooledConnection con) {
-
+        
     }
 }
diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java
index 81347b386..8e00c7987 100644
--- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java
+++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java
@@ -30,7 +30,11 @@ import java.sql.Statement;
 import org.apache.juli.logging.Log;
 import org.apache.juli.logging.LogFactory;
 import org.apache.tomcat.jdbc.pool.JdbcInterceptor;
-
+/**
+ * Abstract class that wraps statements and intercepts query executions.
+ * @author fhanik
+ *
+ */
 public abstract class AbstractQueryReport extends AbstractCreateStatementInterceptor {
     //logger
     protected static Log log = LogFactory.getLog(AbstractQueryReport.class);
@@ -67,12 +71,12 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce
 
     /**
      * Invoked when a query execution, a call to execute/executeQuery or executeBatch failed.
-     * @param query
-     * @param args
-     * @param name
-     * @param start
-     * @param t
-     * @return - the SQL that was executed or the string &quot;batch&quot; 
+     * @param query the query that was executed and failed
+     * @param args the arguments to the execution
+     * @param name the name of the method used to execute {@link AbstractCreateStatementInterceptor#executes}
+     * @param start the time the query execution started
+     * @param t the exception that happened
+     * @return - the SQL that was executed or the string &quot;batch&quot; if it was a batch execution 
      */
     protected String reportFailedQuery(String query, Object[] args, final String name, long start, Throwable t) {
         //extract the query string
@@ -85,13 +89,13 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce
     }
 
     /**
-     * Invoked when a query execution, a call to execute/executeQuery or executeBatch succeeded but was below the threshold
-     * @param query
-     * @param args
-     * @param name
-     * @param start
-     * @param delta
-     * @return - the SQL that was executed or the string &quot;batch&quot; 
+     * Invoked when a query execution, a call to execute/executeQuery or executeBatch succeeded and was within the timing threshold
+     * @param query the query that was executed and failed
+     * @param args the arguments to the execution
+     * @param name the name of the method used to execute {@link AbstractCreateStatementInterceptor#executes}
+     * @param start the time the query execution started
+     * @param delta the time the execution took
+     * @return - the SQL that was executed or the string &quot;batch&quot; if it was a batch execution 
      */
     protected String reportQuery(String query, Object[] args, final String name, long start, long delta) {
         //extract the query string
@@ -104,13 +108,13 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce
     }
 
     /**
-     * Invoked when a query execution, a call to execute/executeQuery or executeBatch succeeded but was above the query time threshold
-     * @param query
-     * @param args
-     * @param name
-     * @param start
-     * @param delta
-     * @return - the SQL that was executed or the string &quot;batch&quot; 
+     * Invoked when a query execution, a call to execute/executeQuery or executeBatch succeeded and was exceeded the timing threshold
+     * @param query the query that was executed and failed
+     * @param args the arguments to the execution
+     * @param name the name of the method used to execute {@link AbstractCreateStatementInterceptor#executes}
+     * @param start the time the query execution started
+     * @param delta the time the execution took
+     * @return - the SQL that was executed or the string &quot;batch&quot; if it was a batch execution 
      */
     protected String reportSlowQuery(String query, Object[] args, final String name, long start, long delta) {
         //extract the query string
diff --git a/modules/jdbc-pool/test/org/apache/tomcat/jdbc/test/DefaultTestCase.java b/modules/jdbc-pool/test/org/apache/tomcat/jdbc/test/DefaultTestCase.java
index 90df561e6..47a85f9b1 100644
--- a/modules/jdbc-pool/test/org/apache/tomcat/jdbc/test/DefaultTestCase.java
+++ b/modules/jdbc-pool/test/org/apache/tomcat/jdbc/test/DefaultTestCase.java
@@ -19,16 +19,12 @@ package org.apache.tomcat.jdbc.test;
 import java.lang.reflect.Method;
 import java.util.Properties;
 
-import javax.sql.DataSource;
+import junit.framework.TestCase;
 
 import org.apache.tomcat.dbcp.dbcp.BasicDataSource;
 import org.apache.tomcat.dbcp.dbcp.BasicDataSourceFactory;
-
-import junit.framework.TestCase;
-
 import org.apache.tomcat.jdbc.pool.PoolConfiguration;
 import org.apache.tomcat.jdbc.pool.PoolProperties;
-import org.apache.tomcat.jdbc.pool.DataSourceProxy;
 
 //import com.mchange.v2.c3p0.ComboPooledDataSource;
 //import com.mchange.v2.log.MLevel;
-- 
2.11.0