org.openeai.dbpool
Class EnterpriseConnectionPool

java.lang.Object

  |

  +--org.openeai.OpenEaiObject

        |

        +--org.openeai.dbpool.EnterpriseDbConnectionObject

              |

              +--org.openeai.dbpool.EnterpriseConnectionPool

public class EnterpriseConnectionPool

extends EnterpriseDbConnectionObject

The Enterprise Database Connection pool class. This class acts as a container for Database connections. It provides a mechanism for retrieving those connections as well as initialization and shutdown methods. The actual java.sql.Connection objects are wrapped by the EnterprisePooledConnection.

Configuration Parameters:

These are the configuration parameters specified by the DbConnectionPoolConfig Element associated to this pool.

Name	Required	Description
name	yes	Name of the pool
dbDriverName	yes	JDBC Database driver name
dbConnectString	yes	JDBC URL that is used to connect to the database
dbConnectUserId	yes	User id to connect as
dbConnectPassword	yes	password associated to the user id
dbPoolSize	yes	Initial size of the pool
dbPoolMaxSize	no	Maximum number of connections that may be created by this pool. if this parameter is left out or if zero is specified, the pool will not restrict how large the pool may get at a given time.
dbVerificationString	no	Some SQL string that can be used to test a connection prior to returning it from the pool. This should be a highly efficient statement. If this is not specified, ONLY the Connection.isClosed() method will be used. If the dbDriverName is an Oracle driver a default verification string will be used in addition to the Connection.isClosed

Version:

3.0 beta2 - 28 January 2003

Author:

Tod Jackson (tod@openeai.org), Steve Wheat (steve@openeai.org)

See Also:

EnterpriseDbConnectionObject, EnterprisePooledConnection, DbConnectionPoolConfig

Field Summary

Fields inherited from class org.openeai.OpenEaiObject

logger

Constructor Summary

EnterpriseConnectionPool(DbConnectionPoolConfig dbConfig)
This is the constructor that AppConfig uses when it instantiates an EnterpriseConnectionPool based on information found in an application's deployment XML document.

EnterpriseConnectionPool(java.lang.String poolName)
Constructor

EnterpriseConnectionPool(java.lang.String poolName, java.util.Properties poolProps)

Method Summary

void	closePool() Iterates through the pool and closes all connections.
java.sql.Connection	getConnection() Returns a pre-established Database connection from the pool.
EnterprisePooledConnection	getExclusiveConnection() Returns a pre-established, AVAILABLE pooled connection object from the pool.
int	getMaxPoolSize() Returns the maximum size of the pool.
java.lang.String	getPoolName() Returns the name of the pool as specified in the deployment document for the application.
int	getPoolSize() Returns the size for the pool.
void	initializePool(java.util.Properties props) Based on properties, establishes a configurable number of pre-established connections to a database and adds them to the Pool.
void	releaseExclusiveConnection(EnterprisePooledConnection p) Releases a pooled connection back to the pool.
void	setMaxPoolSize(int maxSize) Sets the maxiumum size of the pool (the maximum number of connections that should be created and stored in the pool).
void	setPoolName(java.lang.String poolName) Sets the name of the pool.
void	setPoolSize(int poolSize) Sets the size of the pool (the number of connections that should be created and stored in the pool).

Methods inherited from class org.openeai.dbpool.EnterpriseDbConnectionObject

getConnectPassword, getConnectString, getConnectUserId, getDriverName, getVerificationQueryString, setConnectPassword, setConnectString, setConnectUserId, setDriverName, setVerificationQueryString

Methods inherited from class org.openeai.OpenEaiObject

addLog4jProperty, getAppName, getDebug, getFromAddr, getLog4jProperties, getMailHost, getMailService, getProperties, getToAddr, initializeLog4j, initializeLog4j, initializeLog4j, setAppName, setDebug, setFromAddr, setMailHost, setMailService, setProperties, setToAddr

Methods inherited from class java.lang.Object

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

Constructor Detail

EnterpriseConnectionPool

public EnterpriseConnectionPool(java.lang.String poolName)

Constructor

EnterpriseConnectionPool

public EnterpriseConnectionPool(java.lang.String poolName,
                                java.util.Properties poolProps)
                         throws java.sql.SQLException

EnterpriseConnectionPool

public EnterpriseConnectionPool(DbConnectionPoolConfig dbConfig)
                         throws java.sql.SQLException

This is the constructor that AppConfig uses when it instantiates an EnterpriseConnectionPool based on information found in an application's deployment XML document.

Method Detail

getPoolName

public java.lang.String getPoolName()

Returns the name of the pool as specified in the deployment document for the application.

Overrides:

getPoolName in class EnterpriseDbConnectionObject

Returns:

String the pool's name.

setPoolName

public void setPoolName(java.lang.String poolName)

Sets the name of the pool.

Overrides:

setPoolName in class EnterpriseDbConnectionObject

closePool

public void closePool()
               throws java.sql.SQLException

Iterates through the pool and closes all connections.

Throws:

- - SQLException if it can't close a connection.

java.sql.SQLException

setPoolSize

public void setPoolSize(int poolSize)

Sets the size of the pool (the number of connections that should be created and stored in the pool). This is specified in the deployment document for the application being configured and is passed to this object via the DbConnectionPoolConfig object that gets built from that configuration information. If the size passed in is less than or equal to zero, the default size is 1.

getPoolSize

public int getPoolSize()

Returns the size for the pool.

Returns:

int the size of the pool.

setMaxPoolSize

public void setMaxPoolSize(int maxSize)

Sets the maxiumum size of the pool (the maximum number of connections that should be created and stored in the pool). This is specified in the deployment document for the application being configured and is passed to this object via the DbConnectionPoolConfig object that gets built from that configuration information. If no maximum size is specified, the pool will grow based on how busy the application using this pool is. There will always be at least the number of initial connections created. As exclusive connections are retrieved there may be more connections added to the pool. Exclusive connections will be closed and released when the user of the pool is done with the connection and calls the releaseExclusiveConnection method.

getMaxPoolSize

public int getMaxPoolSize()

Returns the maximum size of the pool.

Returns:

int the maximum size of the pool.

initializePool

public void initializePool(java.util.Properties props)
                    throws java.sql.SQLException

Based on properties, establishes a configurable number of pre-established connections to a database and adds them to the Pool. These connections can then be retrieved from the pool via the getConnection() method. The properties are all generally retrieved from the DbConnectionPoolConfig object used to construct this object.

Throws:

- - SQLException if it has any problems establishing connections given the properties passed in.

java.sql.SQLException

getConnection

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

Returns a pre-established Database connection from the pool. Prior to returning the connection, it checks its state and re-establishes a clean connection if the connection has been broken for some reason.

NOTE: This method should only be used if the connection is going to be used in non-transacted mode (autocommit=true). If the connection will be used for multiple transactions in a single logical unit of work, you should use getExclusiveConnection. This method returns a connection regardless of whether or not it is in use so it could be possible that two threads attempt to use a connection returned from this method at the same time. This would NOT be good.

Returns:

- Connection pre-established.

Throws:

- - SQLException if it can't obtain a clean connection.

java.sql.SQLException

getExclusiveConnection

public EnterprisePooledConnection getExclusiveConnection()
                                                  throws java.sql.SQLException

Returns a pre-established, AVAILABLE pooled connection object from the pool. If an avaliable pooled connection cannot be obtained, it will create a new one and return it unless the maximum number of connections for the pool has been reached (maxPoolSize). After the calling application is finished with the pooled connect, it will release that connection making it available for others.

This method ensures that the connection being returned is not being used and will mark the connection as "in-use" so no one else will use the connection.

Returns:

EnterprisePooledConnection which contains a pre-established Connection.

Throws:

java.sql.SQLException - if it can't obtain an available connection.

See Also:

releaseExclusiveConnection(org.openeai.dbpool.EnterprisePooledConnection)

releaseExclusiveConnection

public void releaseExclusiveConnection(EnterprisePooledConnection p)
                                throws java.sql.SQLException

Releases a pooled connection back to the pool. This means, the connection being released will again be available for use by subsequent calls.

If the connection being released, was not one of the original connections created by the pool, it will be closed unless the maximum pool size property is greater than zero and the actual pool size is less than that maximum size.

Throws:

java.sql.SQLException - if errors occur closing the connection (if appropriate)

See Also:

getExclusiveConnection()