amy/venice-main-classic
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

added javadoc comments to some database classes

Browse Source
This commit is contained in:
Eric J. Bowersox 2001-11-15 08:30:13 +00:00
parent ef629c8e48
commit 33eecf87fc
2 changed files with 173 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
src/com/silverwrist/venice/db/DataPool.java
View File

@ -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)
{ // 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();

107
src/com/silverwrist/venice/db/SQLUtil.java
View File

@ -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 &lt;erbo@silcom.com&gt;
* @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))
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<str.length(); i++)
{ // loop through the string encoding its characters
char c = str.charAt(i);
switch (c)
while (ndx>=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