From 33eecf87fc4e02f049e430ca6a7e0b0aeb03858c Mon Sep 17 00:00:00 2001 From: "Eric J. Bowersox" Date: Thu, 15 Nov 2001 08:30:13 +0000 Subject: [PATCH] added javadoc comments to some database classes --- src/com/silverwrist/venice/db/DataPool.java | 95 ++++++++++++++--- src/com/silverwrist/venice/db/SQLUtil.java | 107 ++++++++++++++++---- 2 files changed, 173 insertions(+), 29 deletions(-) diff --git a/src/com/silverwrist/venice/db/DataPool.java b/src/com/silverwrist/venice/db/DataPool.java index c3de7be..b8a308e 100644 --- a/src/com/silverwrist/venice/db/DataPool.java +++ b/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 , * 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.

+ * Based on some code from Marty Hall's Core Servlets and Java Server Pages (Prentice Hall/ + * Sun Microsystems, 2000). + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @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 <database/> 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 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 - avail_connections.addElement(c); - notifyAll(); // wake up! Got a new connection for you! + if (c!=null) + { // move from one vector to another + 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(); diff --git a/src/com/silverwrist/venice/db/SQLUtil.java b/src/com/silverwrist/venice/db/SQLUtil.java index acc940f..a38bbaf 100644 --- a/src/com/silverwrist/venice/db/SQLUtil.java +++ b/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 null. + * @return The SQL-encoded equivalent of str. If str is + * null, returns null. + * @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 null. + * @return The SQL-encoded equivalent of str, in quotes. If str is + * null, 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 null. + * @return The SQL-encoded equivalent of str. If str is + * null, returns null. + */ public static String encodeStringWildcards(String str) { - if ((str.indexOf('_')<0) && (str.indexOf('%')<0)) - return StringUtil.encodeStringSQL(str); - + if (str==null) + 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=0) + { // append the matched "head" and then the encoded character + if (ndx>0) + buf.append(str.substring(0,ndx)); + switch (str.charAt(ndx++)) { - case '\'': - buf.append("\'\'"); + case '%': + buf.append("\\%"); break; case '_': buf.append("\\_"); break; - case '%': - buf.append("\\%"); - break; - - default: - buf.append(c); + case '\'': + buf.append("\'\'"); 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 -