org.osesb.utilities.jdbc
Class DriverConnectionManager

java.lang.Object
  org.osesb.utilities.jdbc.DriverConnectionManager

All Implemented Interfaces:

java.lang.Runnable, IConnectionManager

public class DriverConnectionManager
extends java.lang.Object
implements IConnectionManager, java.lang.Runnable

DriverConnectionManager is an implementation of IConnectionManager that starts and maintains a plain old JDBC connection using java.sql.DriverManagerDriver and properties in a JDBCConfiguration.

The purpose of a IConnectionManager is to hide how database connections are managed. Components that use a IConnectionManager call getConnection() and releaseConnection() and do not need to determine whether the connection is returned by a java.sqlDriverManager or a javax.sql DataDource.

A DriverConnectionManager can be constructed directly using a JDBCConfiguration or the createConnectionManager() method in JDBCConfiguration can be invoked to return a DriverConnectionManager.

Optionally, this class will periodically test the managed connection. If jdbcConfiguration.getdbPingIntervalSeconds() > 0, this object starts a Thread that periodically tests the JDBC connection. If the test fails, then the connection is re-established.

Use reset() to close the managed connection. Use stop() to end the DriverConnectionManager thread and close the connection.

Note: Each JDBC connection creates a separate backend agent that serves as the context for a Connection. The Java connection and statement objects are thread safe, and access to the connection is serialized.

Field Summary

protected java.sql.Connection	dbConn the DB connection.
protected long	dbPingIntervalSeconds If dbPingIntervalSeconds > 0, dbPingThread periodically tests dbConn and the connection is re-established, if needed.
protected java.lang.String	dbPingSQLStatement If dbPingIntervalSeconds > 0, then DriverConnectionManager starts a Thread that periodically tests dbConn and the connection is re-established, if needed.
protected java.lang.Thread	dbPingThread If dbPingIntervalSeconds > 0, then when DriverConnectionManager creates a connection, it starts a Thread that periodically tests dbConn and the connection is re-established, if needed.
protected JDBCConfiguration	jdbcConfiguration The JDBCConfiguration properties.
protected java.lang.String	thisClassName The full name of this class.
protected java.util.Date	timeDBPingThreadStarted The time dbPingThread started.

Constructor Summary

DriverConnectionManager(JDBCConfiguration jdbcConfiguration)
Creates a new DriverConnectionManager with the given JDBC Configuration.

Method Summary

protected void	closeConnection() Close the configured database connection.
protected void	createConnection() Creates a new database connection for this DriverConnectionManager according to the connection properties in jdbcConfiguration and starts a dbPingThread if dbPingIntervalSeconds > 0.
protected void	dbPing() Test the configured database connection.
void	finalize() just maybe...
java.sql.Connection	getConnection() Returns the database connection, according to the properties in jdbcConfiguration, creating a new connection, if necessary.
long	getDbPingIntervalSeconds() Return dbPingIntervalSeconds, which is the interval between tests of database connection.
protected java.lang.String	getDbPingSQLStatement() Return dbPingSQLStatement, which is the SQL statement used to test the database connection.
static void	main(java.lang.String[] args) Main method for testing.
void	releaseConnection(java.sql.Connection dbConn) Releases the database connection.
void	reset() Resets the connection manager.
void	run() Test the configured database connection at intervals specifiec by dbPingIntervalSeconds.
void	setDbPingIntervalSeconds(long dbPingIntervalSeconds) Set dbPingIntervalSeconds, which is the interval between tests of database connection.
protected void	setDbPingSQLStatement(java.lang.String dbPingSQLStatement) Set dbPingSQLStatement, which is the SQL statement used to test the database connection.
void	stop() End DriverConnectionManager#run() and closeConnection.

Methods inherited from class java.lang.Object

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

Field Detail

thisClassName

protected java.lang.String thisClassName

The full name of this class.

jdbcConfiguration

protected JDBCConfiguration jdbcConfiguration

The JDBCConfiguration properties.

dbConn

protected java.sql.Connection dbConn

the DB connection.

dbPingIntervalSeconds

protected long dbPingIntervalSeconds

If dbPingIntervalSeconds > 0, dbPingThread periodically tests dbConn and the connection is re-established, if needed.

dbPingSQLStatement

protected java.lang.String dbPingSQLStatement

If dbPingIntervalSeconds > 0, then DriverConnectionManager starts a Thread that periodically tests dbConn and the connection is re-established, if needed.

By default, dbPingThread tests the connection by retrieving connection meta-data. However, this test is not sufficient for all databases and drivers. So, in these situations, specify a SQL statement that is used to test the connection. The statement cannot be parameterized.

dbPingThread

protected java.lang.Thread dbPingThread

If dbPingIntervalSeconds > 0, then when DriverConnectionManager creates a connection, it starts a Thread that periodically tests dbConn and the connection is re-established, if needed.

See Also:

createConnection()

timeDBPingThreadStarted

protected java.util.Date timeDBPingThreadStarted

The time dbPingThread started.

Constructor Detail

DriverConnectionManager

public DriverConnectionManager(JDBCConfiguration jdbcConfiguration)
                        throws java.lang.Exception

Creates a new DriverConnectionManager with the given JDBC Configuration.

Parameters:

jdbcConfiguration - The JDBCConfiguration to use for this DriverConnectionManager.

Throws:

java.lang.Exception - if constructed with a null jdbcConfiguration.

Method Detail

getConnection

public java.sql.Connection getConnection()
                                  throws java.lang.Exception

Returns the database connection, according to the properties in jdbcConfiguration, creating a new connection, if necessary.

The method is synchronized to make the access to dbConn thread-safe between the owner of this DriverConnectionManager and the dbPing thread.

java.sql.Connection is Thread-safe, and will serialize requests.

If dbPingIntervalSeconds > 0, dbPingThread periodically tests dbConn and the connection is re-established, if needed.

Specified by:

getConnection in interface IConnectionManager

Returns:

A connection to the configured database.

Throws:

java.lang.Exception - if an error occurs while loading the JDBC driver or obtaining a connection.

createConnection

protected void createConnection()
                         throws java.lang.Exception

Creates a new database connection for this DriverConnectionManager according to the connection properties in jdbcConfiguration and starts a dbPingThread if dbPingIntervalSeconds > 0.

Throws:

java.lang.Exception - if an error occurs while loading the JDBC driver or obtaining a connection.

releaseConnection

public void releaseConnection(java.sql.Connection dbConn)

Releases the database connection. The method is synchronized to make the access to dbConn thread-safe between the owner of this DriverConnectionManager and the dbPing thread.

Specified by:

releaseConnection in interface IConnectionManager

Parameters:

dbConn - A Connection obtained using a previous call to getConnection().

reset

public void reset()

Resets the connection manager.

The method is synchronized to make the access to dbConn thread-safe between the owner of this DriverConnectionManager and the dbPing thread.

Specified by:

reset in interface IConnectionManager

run

public void run()

Test the configured database connection at intervals specifiec by dbPingIntervalSeconds. Thread is started when getConnection() is called for the first time.

Specified by:

run in interface java.lang.Runnable

dbPing

protected void dbPing()

Test the configured database connection.

stop

public void stop()

End DriverConnectionManager#run() and closeConnection.

Specified by:

stop in interface IConnectionManager

closeConnection

protected void closeConnection()

Close the configured database connection.

The method is synchronized to make the access to dbConn thread-safe between the owner of this DriverConnectionManager and the dbPing thread.

getDbPingIntervalSeconds

public long getDbPingIntervalSeconds()

Return dbPingIntervalSeconds, which is the interval between tests of database connection.

If dbPingIntervalSeconds > 0, then DriverConnectionManager starts a Thread that periodically tests the database connection and the connection is re-established, if needed.

Returns:

the interval, in seconds, between tests of the database connection.

setDbPingIntervalSeconds

public void setDbPingIntervalSeconds(long dbPingIntervalSeconds)

Set dbPingIntervalSeconds, which is the interval between tests of database connection.

If dbPingIntervalSeconds > 0, then DriverConnectionManager starts a Thread that periodically tests the database connection and the connection is re-established, if needed.

Parameters:

dbPingIntervalSeconds - the interval, in seconds, between tests of the database connection.

getDbPingSQLStatement

protected java.lang.String getDbPingSQLStatement()

Return dbPingSQLStatement, which is the SQL statement used to test the database connection.

If dbPingIntervalSeconds > 0, then DriverConnectionManager starts a Thread that periodically tests the database connection and the connection is re-established, if needed.

By default, dbPingThread tests the connection by retrieving connection meta-data. However, this test is not sufficient for all databases and drivers. So, in these situations, specify a SQL statement that is used to test the connection. The statement cannot be parameterized.

Returns:

the SQL statement that is used to test the database connection.

setDbPingSQLStatement

protected void setDbPingSQLStatement(java.lang.String dbPingSQLStatement)

Set dbPingSQLStatement, which is the SQL statement used to test the database connection.

If dbPingIntervalSeconds > 0, then DriverConnectionManager starts a Thread that periodically tests the database connection and the connection is re-established, if needed.

By default, dbPingThread tests the connection by retrieving connection meta-data. However, this test is not sufficient for all databases and drivers. So, in these situations, specify a SQL statement that is used to test the connection. The statement cannot be parameterized.

Parameters:

dbPingSQLStatement - The SQL statement that is used to test the database connection.

finalize

public void finalize()

just maybe...

Overrides:

finalize in class java.lang.Object

main

public static void main(java.lang.String[] args)

Main method for testing.

Parameters:

args - The test data directory.