gov.nih.nci.caBIO.db
Class DbConnectionBroker

java.lang.Object
  gov.nih.nci.caBIO.db.DbConnectionBroker

All Implemented Interfaces:

java.lang.Runnable

public class DbConnectionBroker

extends java.lang.Object

implements java.lang.Runnable

DbConnectionBroker A servlet-based broker for database connections. Creates and manages a pool of database connections.

Version:

1.0.13 3/12/02

Author:

Marc A. Mnich

Field Summary

private boolean	available
private long[]	connCreateDate
private java.lang.String[]	connID
private int	connLast
private long[]	connLockTime
private java.sql.Connection[]	connPool
private int[]	connStatus
private int	currConnections
private java.sql.SQLWarning	currSQLWarning
private java.lang.String	dbDriver
private java.lang.String	dbLogin
private java.lang.String	dbPassword
private java.lang.String	dbServer
private int	debugLevel
private int	DEFAULTDEBUGLEVEL
private int	DEFAULTMAXCHECKOUTSECONDS
private java.io.PrintWriter	log
private java.lang.String	logFileString
private int	maxCheckoutSeconds
private int	maxConnMSec
private int	maxConns
private int	minConns
private java.lang.String	pid
private java.lang.Thread	runner
private static int	TOLERANCE_LIMIT

Constructor Summary

DbConnectionBroker(java.lang.String dbDriver, java.lang.String dbServer, java.lang.String dbLogin, java.lang.String dbPassword, int minConns, int maxConns, java.lang.String logFileString, double maxConnTime)
Creates a new Connection Broker
dbDriver: JDBC driver.

DbConnectionBroker(java.lang.String dbDriver, java.lang.String dbServer, java.lang.String dbLogin, java.lang.String dbPassword, int minConns, int maxConns, java.lang.String logFileString, double maxConnTime, boolean logAppend)

DbConnectionBroker(java.lang.String dbDriver, java.lang.String dbServer, java.lang.String dbLogin, java.lang.String dbPassword, int minConns, int maxConns, java.lang.String logFileString, double maxConnTime, boolean logAppend, int maxCheckoutSeconds, int debugLevel)

Method Summary

private void	createConn(int i)
void	destroy() Less safe shutdown.
void	destroy(int millis) Multi-phase shutdown.
java.lang.String	freeConnection(java.sql.Connection conn) Frees a connection.
private java.sql.Connection	getAConnection() This method hands out the connections in round-robin order.
long	getAge(java.sql.Connection conn) Returns the age of a connection -- the time since it was handed out to an application.
java.sql.Connection	getConnection()
int	getSize() Returns the number of connections in the dynamic pool.
int	getUseCount() Returns the number of connections in use.
int	idOfConnection(java.sql.Connection conn) Returns the local JDBC ID for a connection.
void	run() Housekeeping thread.
private void	setupBroker(java.lang.String dbDriver, java.lang.String dbServer, java.lang.String dbLogin, java.lang.String dbPassword, int minConns, int maxConns, java.lang.String logFileString, double maxConnTime, boolean logAppend, int maxCheckoutSeconds, int debugLevel)

Methods inherited from class java.lang.Object

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

Field Detail

TOLERANCE_LIMIT

private static final int TOLERANCE_LIMIT

See Also:

Constant Field Values

runner

private java.lang.Thread runner

connPool

private java.sql.Connection[] connPool

connStatus

private int[] connStatus

connLockTime

private long[] connLockTime

connCreateDate

private long[] connCreateDate

connID

private java.lang.String[] connID

dbDriver

private java.lang.String dbDriver

dbServer

private java.lang.String dbServer

dbLogin

private java.lang.String dbLogin

dbPassword

private java.lang.String dbPassword

logFileString

private java.lang.String logFileString

currConnections

private int currConnections

connLast

private int connLast

minConns

private int minConns

maxConns

private int maxConns

maxConnMSec

private int maxConnMSec

maxCheckoutSeconds

private int maxCheckoutSeconds

debugLevel

private int debugLevel

available

private boolean available

log

private java.io.PrintWriter log

currSQLWarning

private java.sql.SQLWarning currSQLWarning

pid

private java.lang.String pid

DEFAULTMAXCHECKOUTSECONDS

private final int DEFAULTMAXCHECKOUTSECONDS

See Also:

Constant Field Values

DEFAULTDEBUGLEVEL

private final int DEFAULTDEBUGLEVEL

See Also:

Constant Field Values

Constructor Detail

DbConnectionBroker

public DbConnectionBroker(java.lang.String dbDriver,
                          java.lang.String dbServer,
                          java.lang.String dbLogin,
                          java.lang.String dbPassword,
                          int minConns,
                          int maxConns,
                          java.lang.String logFileString,
                          double maxConnTime)
                   throws java.io.IOException

Creates a new Connection Broker
dbDriver: JDBC driver. e.g. 'oracle.jdbc.driver.OracleDriver'
dbServer: JDBC connect string. e.g. 'jdbc:oracle:thin:@203.92.21.109:1526:orcl'
dbLogin: Database login name. e.g. 'Scott'
dbPassword: Database password. e.g. 'Tiger'
minConns: Minimum number of connections to start with.
maxConns: Maximum number of connections in dynamic pool.
logFileString: Absolute path name for log file. e.g. 'c:/temp/mylog.log'
maxConnTime: Time in days between connection resets. (Reset does a basic cleanup)
logAppend: Append to logfile (optional)
maxCheckoutSeconds: Max time a connection can be checked out before being recycled. Zero value turns option off, default is 60 seconds. debugLevel: Level of debug messages output to the log file. 0 -> no messages, 1 -> Errors, 2 -> Warnings, 3 -> Information

DbConnectionBroker

public DbConnectionBroker(java.lang.String dbDriver,
                          java.lang.String dbServer,
                          java.lang.String dbLogin,
                          java.lang.String dbPassword,
                          int minConns,
                          int maxConns,
                          java.lang.String logFileString,
                          double maxConnTime,
                          boolean logAppend)
                   throws java.io.IOException

DbConnectionBroker

public DbConnectionBroker(java.lang.String dbDriver,
                          java.lang.String dbServer,
                          java.lang.String dbLogin,
                          java.lang.String dbPassword,
                          int minConns,
                          int maxConns,
                          java.lang.String logFileString,
                          double maxConnTime,
                          boolean logAppend,
                          int maxCheckoutSeconds,
                          int debugLevel)
                   throws java.io.IOException

Method Detail

setupBroker

private void setupBroker(java.lang.String dbDriver,
                         java.lang.String dbServer,
                         java.lang.String dbLogin,
                         java.lang.String dbPassword,
                         int minConns,
                         int maxConns,
                         java.lang.String logFileString,
                         double maxConnTime,
                         boolean logAppend,
                         int maxCheckoutSeconds,
                         int debugLevel)
                  throws java.io.IOException

Throws:

java.io.IOException

run

public void run()

Housekeeping thread. Runs in the background with low CPU overhead. Connections are checked for warnings and closure and are periodically restarted. This thread is a catchall for corrupted connections and prevents the buildup of open cursors. (Open cursors result when the application fails to close a Statement). This method acts as fault tolerance for bad connection/statement programming.

Specified by:

run in interface java.lang.Runnable

getAConnection

private java.sql.Connection getAConnection()

This method hands out the connections in round-robin order. This prevents a faulty connection from locking up an application entirely. A browser 'refresh' will get the next connection while the faulty connection is cleaned up by the housekeeping thread. If the min number of threads are ever exhausted, new threads are added up the the max thread count. Finally, if all threads are in use, this method waits 2 seconds and tries again, up to ten times. After that, it returns a null.

getConnection

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

Throws:

java.lang.Exception

idOfConnection

public int idOfConnection(java.sql.Connection conn)

Returns the local JDBC ID for a connection.

freeConnection

public java.lang.String freeConnection(java.sql.Connection conn)

Frees a connection. Replaces connection back into the main pool for reuse.

getAge

public long getAge(java.sql.Connection conn)

Returns the age of a connection -- the time since it was handed out to an application.

createConn

private void createConn(int i)
                 throws java.sql.SQLException

Throws:

java.sql.SQLException

destroy

public void destroy(int millis)
             throws java.sql.SQLException

Multi-phase shutdown. having following sequence:

1. getConnection() will refuse to return connections.
2. The housekeeping thread is shut down.
   Up to the time of millis milliseconds after shutdown of the housekeeping thread, freeConnection() can still be called to return used connections.
3. After millis milliseconds after the shutdown of the housekeeping thread, all connections in the pool are closed.
4. If any connections were in use while being closed then a SQLException is thrown.
5. The log is closed.

Call this method from a servlet destroy() method.

Parameters:

millis - the time to wait in milliseconds.

Throws:

java.sql.SQLException - if connections were in use after millis.

destroy

public void destroy()

Less safe shutdown. Uses default timeout value. This method simply calls the destroy() method with a millis value of 10000 (10 seconds) and ignores SQLException thrown by that method.

See Also:

destroy(int)

getUseCount

public int getUseCount()

Returns the number of connections in use.

getSize

public int getSize()

Returns the number of connections in the dynamic pool.