added javadoc comments to some database classes

src/com/silverwrist/venice/db/DataPool.java

@@ -7,7 +7,7 @@
  * WARRANTY OF ANY KIND, either express or implied. See the License for the specific
  * language governing rights and limitations under the License.
  * 
- * The Original Code is the Venice Web Community System.
+ * The Original Code is the Venice Web Communities System.
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
@@ -24,6 +24,16 @@ import org.w3c.dom.*;
 import com.silverwrist.util.DOMElementHelper;
 import com.silverwrist.venice.core.ConfigException;
 
+/**
+ * A simple pooling system for JDBC connections, which allows connections to be kept in a pool until
+ * they're needed, avoiding the overhead of opening and closing connections for each transaction, or
+ * keeping one database connection open for each user.<P>
+ * Based on some code from Marty Hall's <EM>Core Servlets and Java Server Pages</EM> (Prentice Hall/
+ * Sun Microsystems, 2000).
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public class DataPool implements Runnable
 {
   /*--------------------------------------------------------------------------------
@@ -31,7 +41,7 @@ public class DataPool implements Runnable
    *--------------------------------------------------------------------------------
    */
 
-  private static Category logger = Category.getInstance(DataPool.class.getName());
+  private static Category logger = Category.getInstance(DataPool.class);
 
   /*--------------------------------------------------------------------------------
    * Attributes
@@ -53,6 +63,13 @@ public class DataPool implements Runnable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Creates and configures a new database pool, based on a section from the Venice configuration file.
+   *
+   * @param cfg The &lt;database/&gt; section of the configuration file.
+   * @exception com.silverwrist.venice.core.ConfigException The configuration is not correct in some way.
+   * @exception java.sql.SQLException If the initial connections could not be created.
+   */
   public DataPool(Element cfg) throws ConfigException, SQLException
   {
     // Make sure they passed the <database/> section to us.
@@ -194,16 +211,14 @@ public class DataPool implements Runnable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Called by the garbage collector on an object when garbage collection determines that there are no
+   * more references to the object.
+   */
   protected void finalize()
   {
     closeConnections(avail_connections);
-    avail_connections = null;
     closeConnections(busy_connections);
-    busy_connections = null;
-    driver = null;
-    url = null;
-    username = null;
-    password = null;
 
   } // end finalize
 
@@ -212,6 +227,12 @@ public class DataPool implements Runnable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Creates and returns a new database connection.
+   *
+   * @return The new database connection object.
+   * @exception java.sql.SQLException An error prevented the creation of the connection.
+   */
   private Connection makeNewConnection() throws SQLException
   {
     try
@@ -242,6 +263,11 @@ public class DataPool implements Runnable
 
   } // end makeNewConnection
 
+  /**
+   * Spins off a background thread to create a new database connection.
+   *
+   * @see #run()
+   */
   private void makeBackgroundConnection()
   {
     pending = true;
@@ -260,7 +286,12 @@ public class DataPool implements Runnable
 
   } // end makeBackgroundConnection
 
-  private void closeConnections(Vector vconn)
+  /**
+   * Closes all database connections in the specified vector.
+   *
+   * @param vconn Vector of connections to be closed.
+   */
+  private static void closeConnections(Vector vconn)
   {
     if (logger.isDebugEnabled())
       logger.debug("closeConnections(" + String.valueOf(vconn.size()) + " to be closed)");
@@ -289,6 +320,14 @@ public class DataPool implements Runnable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * The thread function which creates a new connection and adds it to the list of available
+   * connections "in the background."  It then notifies all threads which are waiting for a
+   * new connection.
+   *
+   * @see #makeBackgroundConnection()
+   * @see #makeNewConnection()
+   */
   public void run()
   {
     try
@@ -319,6 +358,11 @@ public class DataPool implements Runnable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the number of connections currently managed by this pool.
+   *
+   * @return The number of connections currently managed by this pool.
+   */
   public synchronized int numConnections()
   {
     int rc = avail_connections.size() + busy_connections.size();
@@ -328,6 +372,14 @@ public class DataPool implements Runnable
 
   } // end numConnections
 
+  /**
+   * Attempts to get a database connection from the pool, waiting for one if the "wait-if-busy" flag was set
+   * in the data pool's configuration.
+   *
+   * @return A new database connection.
+   * @exception java.sql.SQLException The connection limit was reached, or an error prevented the creation
+   *            of another connection.
+   */
   public synchronized Connection getConnection() throws SQLException
   {
     for (;;)
@@ -387,14 +439,28 @@ public class DataPool implements Runnable
 
   } // end getConnection
 
+  /**
+   * Returns a database connection to the pool.
+   *
+   * @param c The connection to be returned to the pool.
+   */
   public synchronized void releaseConnection(Connection c)
   {
-    busy_connections.removeElement(c); // move from one vector to another
+    if (c!=null)
-    avail_connections.addElement(c);
+    { // move from one vector to another
-    notifyAll();  // wake up!  Got a new connection for you!
+      busy_connections.removeElement(c);
+      avail_connections.addElement(c);
+      notifyAll();  // wake up!  Got a new connection for you!
+
+    } // end if
 
   } // end releaseConnection
 
+  /**
+   * Closes all connections managed by this data pool.
+   *
+   * @see #closeConnections(java.util.Vector)
+   */
   public synchronized void closeAllConnections()
   {
     if (logger.isDebugEnabled())
@@ -406,6 +472,11 @@ public class DataPool implements Runnable
 
   } // end closeAllConnections
 
+  /**
+   * Returns a string reflecting the current state of the data pool, commonly used for debugging.
+   *
+   * @return The debugging string for this pool.
+   */
   public synchronized String toString()
   {
     StringBuffer info = new StringBuffer();

src/com/silverwrist/venice/db/SQLUtil.java

@@ -19,8 +19,16 @@ package com.silverwrist.venice.db;
 
 import java.sql.*;
 import java.util.*;
+import com.silverwrist.util.AnyCharMatcher;
 import com.silverwrist.util.StringUtil;
 
+/**
+ * Utility functions commonly used for passing string values to SQL commands, and interpreting the results.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ * @see com.silverwrist.util.StringUtil
+ */
 public class SQLUtil
 {
   /*--------------------------------------------------------------------------------
@@ -28,6 +36,9 @@ public class SQLUtil
    *--------------------------------------------------------------------------------
    */
 
+  private static final String SQL_WILDCARD_CHARS = "%_'";
+
+  // used to convert dates and times to UTC for sending to SQL
   private static SimpleTimeZone utc = new SimpleTimeZone(0,"UTC");
 
   /*--------------------------------------------------------------------------------
@@ -35,6 +46,13 @@ public class SQLUtil
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Converts a date-and-time string (an SQL DATETIME value) to a standard Java date.
+   *
+   * @param dstr The date-and-time string to convert, presumed to be in UTC.
+   * @return The converted date and time.
+   * @exception java.sql.SQLException The date and time string was in an invalid format.
+   */
   private static java.util.Date convertDateTimeString(String dstr) throws SQLException
   {
     if (dstr==null)
@@ -65,12 +83,31 @@ public class SQLUtil
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Performs SQL encoding of an arbitrary string.  When a string is SQL-encoded, all single-quote
+   * characters are doubled, and all other characters are left untouched.
+   *
+   * @param str The string to be SQL-encoded.  May be <CODE>null</CODE>.
+   * @return The SQL-encoded equivalent of <CODE>str</CODE>.  If <CODE>str</CODE> is
+   *         <CODE>null</CODE>, returns <CODE>null</CODE>.
+   * @see com.silverwrist.util.StringUtil#encodeStringSQL(java.lang.String)
+   */
   public static String encodeString(String str)
   {
     return StringUtil.encodeStringSQL(str);
 
   } // end encodeString
 
+  /**
+   * Performs SQL encoding of an arbitrary string, enclosing it in quotes, so that it may be passed as an
+   * argument in an SQL statement.  When a string is SQL-encoded, all single-quote characters are doubled,
+   * and all other characters are left untouched.
+   *
+   * @param str The string to be SQL-encoded.  May be <CODE>null</CODE>.
+   * @return The SQL-encoded equivalent of <CODE>str</CODE>, in quotes.  If <CODE>str</CODE> is
+   *         <CODE>null</CODE>, returns "NULL".
+   * @see com.silverwrist.util.StringUtil#encodeStringSQL(java.lang.String)
+   */
   public static String encodeStringArg(String str)
   {
     if (str==null)
@@ -81,41 +118,62 @@ public class SQLUtil
 
   } // end encodeStringArg
 
+  /**
+   * Performs SQL-encoding of a string which may contain the SQL wildcard characters, '%' and '_'.  The
+   * wildcard characters are escaped with '\', and the single-quote characters are doubled, but all other
+   * characters are left untouched.
+   *
+   * @param str The string to be SQL-encoded.  May be <CODE>null</CODE>.
+   * @return The SQL-encoded equivalent of <CODE>str</CODE>.  If <CODE>str</CODE> is
+   *         <CODE>null</CODE>, returns <CODE>null</CODE>.
+   */
   public static String encodeStringWildcards(String str)
   {
-    if ((str.indexOf('_')<0) && (str.indexOf('%')<0))
+    if (str==null)
-      return StringUtil.encodeStringSQL(str);
+      return null;  // safety feature
-
+    AnyCharMatcher nhc = new AnyCharMatcher(SQL_WILDCARD_CHARS);
+    int ndx = nhc.get(str);
+    if (ndx<0)
+      return str;   // trivial short-circuit case
     StringBuffer buf = new StringBuffer();
-    for (int i=0; i<str.length(); i++)
+    while (ndx>=0)
-    { // loop through the string encoding its characters
+    { // append the matched "head" and then the encoded character
-      char c = str.charAt(i);
+      if (ndx>0)
-      switch (c)
+	buf.append(str.substring(0,ndx));
+      switch (str.charAt(ndx++))
       {
-	case '\'':
+	case '%':
-	  buf.append("\'\'");
+	  buf.append("\\%");
 	  break;
 
 	case '_':
 	  buf.append("\\_");
 	  break;
 
-	case '%':
+	case '\'':
-	  buf.append("\\%");
+	  buf.append("\'\'");
-	  break;
-
-	default:
-	  buf.append(c);
 	  break;
 
       } // end switch
 
-    } // end for
+      if (ndx==str.length())
+	return buf.toString();  // munched the entire string - all done!
+      str = str.substring(ndx);
+      ndx = nhc.get(str);
 
+    } // end while
+
+    buf.append(str);  // append the unmatched tail
     return buf.toString();
 
   } // end encodeStringWildcards
 
+  /**
+   * Encodes a date as an SQL date/time string, expressed in UTC.
+   *
+   * @param d The date to be encoded.
+   * @return The string equivalent of that date.
+   */
   public static String encodeDate(java.util.Date d)
   {
     // Break down the date as a UTC value.
@@ -167,12 +225,28 @@ public class SQLUtil
 
   } // end encodeDate
 
+  /**
+   * Returns the value of a DATETIME column in the current row of an SQL result set, formatted as a date.
+   *
+   * @param rs The result set to look in.
+   * @param column The name of the column to be returned.
+   * @return The value of the specified column, expressed as a date.
+   * @exception java.sql.SQLException If the column could not be retrieved or converted.
+   */
   public static java.util.Date getFullDateTime(ResultSet rs, String column) throws SQLException
   {
     return convertDateTimeString(rs.getString(column));
 
   } // end getFullDateTime
 
+  /**
+   * Returns the value of a DATETIME column in the current row of an SQL result set, formatted as a date.
+   *
+   * @param rs The result set to look in.
+   * @param column The 1-based index of the column to be returned.
+   * @return The value of the specified column, expressed as a date.
+   * @exception java.sql.SQLException If the column could not be retrieved or converted.
+   */
   public static java.util.Date getFullDateTime(ResultSet rs, int column) throws SQLException
   {
     return convertDateTimeString(rs.getString(column));
@@ -180,4 +254,3 @@ public class SQLUtil
   } // end getFullDateTime
 
 } // end class SQLUtil
-