edu.jhu.tmaj.database.conn
Class PooledConnectionManager

java.lang.Object
  edu.jhu.tmaj.database.conn.PooledConnectionManager

All Implemented Interfaces:

ConnectionManager

final class PooledConnectionManager
extends java.lang.Object
implements ConnectionManager

A connection factory that supports and reuses multiple connections to the database in a thread-safe manner. This class insists that connections be returned with returnConnection() after they are for SQL statements, otherwise they are lost and will not be used again. We refer to it as a Connection leak if a client of this class fails to return a connection, and an OutOfConnections Exception is likely to be thrown. The default maximum number of simulatenous connections is declared in the DEFAULT_MAX_CONNECTIONS variable. You may specify the maximum in the constructor. This class refuses to open more connections than what is specified as the maximum number of connections. If this class has to wait longer than MAX_TIME_TO_WAIT_FOR_FREE_CONNECTION to get a connection from the connection pool, an OutOfConnections SQLException will be thrown.

How a Tomcat Server might use this class:
The tomcat server runs an instance of a webapp (like TMAJ), and each time a client connects to Tomcat, tomcat generates a new thread. (Tomcat does this automatically without any special settings.) The only piece of data that these threads share are the database connections. Thus access to the database connections must be done in a thread-safe manner. Database connections must be shared must generating a new connection for each Request to tomcat would be inefficient since creating a new connection takes a lot of time.

Constructor Summary

PooledConnectionManager(ConnectionFactory connectionFactory, java.lang.String testSqlStatement)
Constructs this object.

Method Summary

java.sql.Connection	getConnection() Returns a shared connection from the connection pool.
void	returnConnection(java.sql.Connection connection) returns the connection allowing other threads to use it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PooledConnectionManager

public PooledConnectionManager(ConnectionFactory connectionFactory,
                               java.lang.String testSqlStatement)

Constructs this object.

Parameters:

maxConnections - the maximum number of connections that this class will hold. Many databases only allow a user to have so many connections open at once.

testSqlStatement - A SQL statement that will be run each time a new connection is returned for the purposes of testing the connection. This should be a statement that runs very fast as it will be run often, and a statement that will not fail. An example statement might be "SELECT ID FROM Users WHERE 1 = 0". This example statement would return no rows, but would definitely fail if something were wrong with the connection.

Method Detail

getConnection

public java.sql.Connection getConnection()
                                  throws java.sql.SQLException

Returns a shared connection from the connection pool. We test connections before we return them to the user, NOT after they are created. This is because connections can be created and be good, but later become "bad" by being timed out by the database.

Specified by:

getConnection in interface ConnectionManager

Returns:

a shared connection to the database that must be returned.

Throws:

java.sql.SQLException - if there is an error making a connection or the class is out of connections

returnConnection

public void returnConnection(java.sql.Connection connection)

returns the connection allowing other threads to use it. If the connection is not returned no other threads may use it and it becomes a "lost" connection

Specified by:

returnConnection in interface ConnectionManager