: Class ConnectionPool

com.bitmechanic.sql
Class ConnectionPool

java.lang.Object
  |
  +--com.bitmechanic.sql.ConnectionPool

public class ConnectionPool

extends java.lang.Object

Individual pool associated with a JDBC datasource and username. Each pool is identified by an alias. Use the alias name to acquire a ref to a Connection from the pool. See the ConnectionPoolManager for further details on how to do this.

Version:

$Id: ConnectionPool.java,v 1.18 2001/07/26 16:28:32 pixel Exp $

Author:

James Cooper

See Also:

ConnectionPoolManager

Constructor Summary

ConnectionPool(java.lang.String alias, java.lang.String url, java.lang.String username, java.lang.String password, int maxConn, int timeoutSeconds, int checkoutSeconds)
Creates a Connection pool with no maxCheckout parameter.

ConnectionPool(java.lang.String alias, java.lang.String url, java.lang.String username, java.lang.String password, int maxConn, int timeoutSeconds, int checkoutSeconds, int maxCheckout)
Creates a Connection pool

Method Summary

java.lang.String	dumpInfo() Dump some information about all connections
java.lang.String	getAlias() Returns the alias for this pool.
boolean	getCacheStatements() Returns whether connections in this pool will cache Statement and PreparedStatement objects.
java.sql.Connection	getConnection() Returns a connection for the pool.
int	getMaxConn() Returns the maximum number of connections this pool can open
int	getNumCheckoutTimeouts() Returns the number of times a Connection has been closed by the reapIdleConnections() method due to being checked out for longer than the checkoutSeconds interval.
int	getNumRequests() Returns the number of times a Connection has been checked out from the pool
int	getNumWaits() Returns the number of times a thread has had to block on wait() as a result of all PooledConnections being in use.
int	getPrefetchSize() Get the current prefetch size
void	reapIdleConnections() Check all connections to make sure they haven't: 1) gone idle for too long 2) been checked out by a thread for too long (cursor leak)
void	removeAllConnections() Removes all connections from the pool and calls close() on them.
void	returnConnection(PooledConnection conn)
void	setCacheStatements(boolean cacheStmts) If set to true, connections in the pool will reuse Statements and PreparedStatements.
void	setPrefetchSize(int newPrefetchSize) Change the number of rows prefetched for a result set, for those drivers that support it.
void	setTracing(boolean on) Turns tracing on or off.
int	size() Returns the current number of Connections in the pool.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConnectionPool

public ConnectionPool(java.lang.String alias,
                      java.lang.String url,
                      java.lang.String username,
                      java.lang.String password,
                      int maxConn,
                      int timeoutSeconds,
                      int checkoutSeconds)

Creates a Connection pool with no maxCheckout parameter.

Parameters:

alias - Name of the pool

url - JDBC URL to connect to

username - JDBC username to connect as

password - username's password in the database

maxConn - Maximum number of connections to open; When this limit is reached, threads requesting a connection are queued until a connection becomes available

timeoutSeconds - Maximum number of seconds a Connection can go unused before it is closed

checkoutSeconds - Maximum number of seconds a Thread can checkout a Connection before it is closed and returned to the pool. This is a protection against the Thread dying and leaving the Connection checked out indefinately

ConnectionPool

public ConnectionPool(java.lang.String alias,
                      java.lang.String url,
                      java.lang.String username,
                      java.lang.String password,
                      int maxConn,
                      int timeoutSeconds,
                      int checkoutSeconds,
                      int maxCheckout)

Creates a Connection pool

Parameters:

alias - Name of the pool

url - JDBC URL to connect to

username - JDBC username to connect as

password - username's password in the database

maxConn - Maximum number of connections to open; When this limit is reached, threads requesting a connection are queued until a connection becomes available

timeoutSeconds - Maximum number of seconds a Connection can go unused before it is closed

checkoutSeconds - Maximum number of seconds a Thread can checkout a Connection before it is closed and returned to the pool. This is a protection against the Thread dying and leaving the Connection checked out indefinately

maxCheckout - If this is greater than 0, the number of times a Connection may be checked out before it is closed. Used as a safeguard against cursor leak, which occurs if you don't call ResultSet.close() and Statement.close()

Method Detail

setCacheStatements

public void setCacheStatements(boolean cacheStmts)

If set to true, connections in the pool will reuse Statements and PreparedStatements. If set to false, connections in the pool will proxy calls to createStatement() and prepareStatement() straight through to the driver.

Set this to false if you want to run multiple Statements over the same Connection.

This is set to 'true' by default.

getCacheStatements

public boolean getCacheStatements()

Returns whether connections in this pool will cache Statement and PreparedStatement objects.

setTracing

public void setTracing(boolean on)

Turns tracing on or off. If turned on, verbose messages about the pool will be printed to STDERR

getAlias

public java.lang.String getAlias()

Returns the alias for this pool. This name is defined by the user in the constructor

getNumRequests

public int getNumRequests()

Returns the number of times a Connection has been checked out from the pool

getNumWaits

public int getNumWaits()

Returns the number of times a thread has had to block on wait() as a result of all PooledConnections being in use. Useful diagnostic tool to see if your pool needs more nodes (which could require a database license upgrade if you're running Oracle for instance)

getNumCheckoutTimeouts

public int getNumCheckoutTimeouts()

Returns the number of times a Connection has been closed by the reapIdleConnections() method due to being checked out for longer than the checkoutSeconds interval.

If this is greater than 0 it means that you either have queries that take longer to execute than the checkoutSeconds interval allows, or it means that you are forgetting to call conn.close() somewhere in your application. Both conditions are undesirable, but they have different solutions. In the latter case either tune your query to execute more quickly, or increase the checkoutSeconds parameter to the pool. In the former case you simply need to find the code that calls DriverManager.getConnection() but not conn.close()

getMaxConn

public int getMaxConn()

Returns the maximum number of connections this pool can open

size

public int size()

Returns the current number of Connections in the pool.

reapIdleConnections

public void reapIdleConnections()

Check all connections to make sure they haven't: 1) gone idle for too long
2) been checked out by a thread for too long (cursor leak)

removeAllConnections

public void removeAllConnections()

Removes all connections from the pool and calls close() on them. It squelches any SQLExceptions that might results from close(). That's probably not ideal.

getConnection

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

Returns a connection for the pool. There are three ways this can happen:

1. If a connection in the pool is free, it is locked and returned immediately
2. If no connections are free, but the pool is not full, a new Connection is opened and returned
3. If no connections are free, and the pool is full, the thread calls wait() and blocks until a connection is returned

returnConnection

public void returnConnection(PooledConnection conn)

dumpInfo

public java.lang.String dumpInfo()

Dump some information about all connections

setPrefetchSize

public void setPrefetchSize(int newPrefetchSize)

Change the number of rows prefetched for a result set, for those drivers that support it.

Parameters:

newPrefetchSize - the new prefetch size to use, -1 for the default

getPrefetchSize

public int getPrefetchSize()

Get the current prefetch size