Since I am eventually going to be using Turbine's connection pool (and
perhaps more of the services it offers), I decided to figure out how
the pool works (which was easy).
I've added some documentation to the pool to hopefully make it even more
clear. I tweaked the implementation of a couple of methods as well,
but didn't modify any of the interfaces or what the methods actually
do. So here's the patch:
Index: ConnectionPool.java
===================================================================
RCS file:
/products/cvs/turbine/turbine/src/java/org/apache/turbine/util/db/pool/ConnectionPool.java,v
retrieving revision 1.4
diff -u -u -r1.4 ConnectionPool.java
--- ConnectionPool.java 2000/06/05 04:41:04 1.4
+++ ConnectionPool.java 2000/06/27 00:04:48
@@ -65,7 +65,8 @@
import org.apache.turbine.services.resources.TurbineResources;
/**
- * This class implements a simple connection pooling scheme.
+ * This class implements a simple connection pooling scheme. Multiple pools
+ * are available through use of the <code>DBBroker</code>.
*
* @author Frank Y. Kim
* @author Brett McLaughlin
@@ -75,25 +76,30 @@
{
/** Pool containing database connections. */
private Stack pool = null;
+
/** The current number of database connections that have been created. */
private int totalConnections = 0;
+
/** The maximum number of database connections that can be created. */
private int maxConnections = 10;
+
/** The amount of time in milliseconds that a connection will be pooled. */
private long expiryTime = 3600000; // 1 hour
- /** The number of times to attempt to obtain a pooled connection before giving
up. */
- private long connectionAttemptsMax = 50;
+
/** The number of times to attempt to obtain a pooled connection before giving
up. */
+ private long maxConnectionAttempts = 50;
v+
+ /** The number of times that an attempt to obtain a pooled connection has been
+made. */
private long connectionAttemptsCounter = 0;
- /** thread sleep time */
- private long checkFrequency = 5000;
+ /** Thread sleep time between checks for database connectivity problems. */
+ private long dbCheckFrequency = 5000;
- /** The class containing database specific info, for the connections in this pool
*/
+ /** The class containing the database specific info for connections in this pool.
+ */
private DB db = null;
/**
- * Constructor that initializes attributes.
+ * Creates a <code>ConnectionPool</code> with the default attributes.
*/
protected ConnectionPool()
{
@@ -101,10 +107,14 @@
maxConnections = TurbineResources.getInt("database.maxConnections", 10);
expiryTime = TurbineResources.getLong("database.expiryTime", 3600000);
- connectionAttemptsMax =
TurbineResources.getLong("database.connectionAttemptsMax", 50);
+ maxConnectionAttempts =
+TurbineResources.getLong("database.maxConnectionAttempts", 50);
}
+
/**
- * Constructor that initializes attributes.
+ * Creates a <code>ConnectionPool</code> with the specified attributes.
+ *
+ * @param maxCons The maximum number of connectinos for this pool.
+ * @param expiryTime The expiration time in milliseconds.
*/
protected ConnectionPool(int maxCons, long expiryTime)
{
@@ -113,8 +123,11 @@
this.maxConnections = maxCons;
this.expiryTime = expiryTime;
}
+
/**
* Close any open connections when this object is garbage collected.
+ *
+ * @exception Throwable Anything might happen. ;)
*/
protected void finalize() throws Throwable
{
@@ -124,6 +137,7 @@
closeConnection(dbcon);
}
}
+
/**
* Returns a connection.
*
@@ -146,10 +160,10 @@
}
/**
- * Returns the database class associated with this pool.
+ * Returns an instance of the database adapter associated with this pool.
*
- * @return a DB.
- * @exception Exception.
+ * @return The <code>DB</code> associated with this pool.
+ * @exception Exception
*/
public DB getDB()
{
@@ -157,15 +171,23 @@
}
/**
- * Returns a connection to the database depending on the type.
+ * Returns a fresh connection to the database. The database type is
+ * specified by <code>driver</code>, and its connection information by
+ * <code>url</code>, <code>username</code>, and <code>password</code>.
*
+ * @param driver The fully-qualified name of the JDBC driver to use.
+ * @param url The URL of the database from which the connection is
+ * desired.
+ * @param username The name of the database user.
+ * @param password The password of the database user.
* @return A database connection.
+ * @exception Exception
*/
private DBConnection getNewConnection(String driver, String url, String username,
String password) throws Exception
{
- // In Turbine, DBBroker keeps a collection of pools, each one of which
contains
- // connections to a single database. So I have modified this ConnectionPool
class
- // so that the initialization only occurs once and is stored as a instance
attribute.
+ // DBBroker keeps a collection of ConnectionPools, each one of which
+ // contains connections to a single database. The initialization of
+ // a pool should only occur once.
if (db == null)
{
db = DBFactory.create( driver );
@@ -174,10 +196,17 @@
totalConnections++;
return new DBConnection( db.getConnection(), url );
}
+
/**
- * Gets a pooled connection from the database.
+ * Gets a pooled database connection.
*
+ * @param driver The fully-qualified name of the JDBC driver to use.
+ * @param url The URL of the database from which the connection is
+ * desired.
+ * @param username The name of the database user.
+ * @param password The password of the database user.
* @return A database connection.
+ * @exception Exception
*/
private synchronized DBConnection getPooledConnection(String driver, String url,
String username, String password) throws Exception
{
@@ -185,9 +214,10 @@
{
if (!pool.empty())
{
- // It's really not safe to assume this connection is valid
- // even though it is checked before being pushed onto the stack
DBConnection con = (DBConnection) pool.pop();
+
+ // It's really not safe to assume this connection is valid
+ // even though it's checked before being pooled.
if (isValid(con))
{
connectionAttemptsCounter = 0;
@@ -223,43 +253,36 @@
* Helper method which determines if a connection has expired.
*
* @param connection The connection to test.
- * @return true if the connection is expired, false otherwise.
+ * @return True if the connection is expired, false otherwise.
+ * @exception Exception
*/
private boolean isExpired( DBConnection connection ) throws Exception
{
- boolean expired = false;
- long createTime = connection.getTimestamp();
- long currentTime = System.currentTimeMillis();
-
- if ( (currentTime - createTime) > expiryTime )
- {
- expired = true;
- }
-
- return expired;
+ // Test the age of the connection (defined as current time minus
+ // connection birthday) against the connection pool expiration time.
+ return (System.currentTimeMillis() - connection.getTimestamp() > expiryTime);
}
+
/**
- * Helper method which determines if a connection is still valid.
+ * Determines if a connection is still valid.
*
* @param connection The connection to test.
- * @return true if the connection is valid, false otherwise.
+ * @return True if the connection is valid, false otherwise.
+ * @exception Exception
*/
private boolean isValid( DBConnection connection ) throws Exception
{
- boolean valid = false;
-
- if ( connection.getConnection() != null &&
- !connection.getConnection().isClosed() &&
- !isExpired(connection) )
- {
- valid = true;
- }
-
- return valid;
+ // Test whether the connection is valid and return the result.
+ return ( connection.getConnection() != null &&
+ !connection.getConnection().isClosed() &&
+ !isExpired(connection) );
}
+
/**
- force a close of a connection
- */
+ * Force the close of a database connection.
+ *
+ * @param dbcon Connection to close.
+ */
private void closeConnection ( DBConnection dbcon )
{
try
@@ -269,18 +292,17 @@
conn.close();
}
catch (Exception e)
- {}
-
-
-
+ {
+ // Currently ignoring a connection close error.
+ }
}
/**
- * Returns a connection to the pool.
- * This method must be called by the requestor to return
- * the connection to the pool.
+ * This method returns a connection to the pool, and <b>must</b> be called
+ * by the requestor when finished with the connection.
*
- * @param A connection to the database.
+ * @param connection The database connection to release.
+ * @exception Exception Trouble releasing the connection.
*/
protected synchronized void releaseConnection(DBConnection connection) throws
Exception
{
@@ -295,20 +317,22 @@
totalConnections--;
}
}
+
/*
This is being left commented for now because it requires more
thought that I'm not ready to give to it yet. -JSS
public void run() {
while(true) {
- // sleep for 5 seconds.
+ // Wait for a bit.
try {
- Thread.sleep(checkFrequency);
+ Thread.sleep(dbCheckFrequency);
} catch(InterruptedException exc) { }
- // dump all connections
- if ( connectionAttemptsCounter >= connectionAttemptsMax )
+ // Check for database connectivity problems.
+ if ( connectionAttemptsCounter >= maxConnectionAttempts )
{
+ // Dump all connections.
try
{
finalize();
------------------------------------------------------------
To subscribe: [EMAIL PROTECTED]
To unsubscribe: [EMAIL PROTECTED]
Search: <http://www.mail-archive.com/turbine%40list.working-dogs.com/>
Problems?: [EMAIL PROTECTED]
