oracle.jbo.server
Interface ConnectionPoolManager

All Known Implementing Classes:

ConnectionPoolManagerImpl, OCIConnectionPoolManagerImpl

public interface ConnectionPoolManager

Declares ConnectionPoolManager operations. If JDBC connection pooling has been enabled, the ConnectionPoolManager is invoked by the DBTransaction class to create and release cached JDBC connection instances.

The connection pool manager is enabled when the client invokes the application module instance amInstance.getTransaction().connect(), and is disabled with amInstance.getTransaction().disconnect(). No other coding is required to use JDBC connection pooling with Business Components for Java 3.2, other than set the MaxPoolSize or InitPoolSize parameters, if you wish.

In contrast, if you have created a custom DBTransaction you will have to implement additional logic in that class to use the JDBC connection pool.

It is only necessary to create a custom connection pool if you already have your own JDBC connection pooling implementation that you would like to use with Business Components for Java. You should invoke code that follows the pattern in the samples below to use the connection pool. For example, this is what the Business Components for Java implementation of DBTransactionImpl performs to use the pool:

Checking out a connection:

    // Get a connection pool manager instance
    // from the connection pool manager factory
       ConnectionPoolManager connectionPoolManager =
       ConnectionPoolManagerFactory.getConnectionPoolManager();

    // Generate a unique signature for the pool.  Assume
    // that the JDBC URL, JDBC user, and JDBC password were
    // all specified as separate properties.  Note that
    // the connection pool key is stored as member variable
    // for later use.
    mConnectionPoolKey = connectionPoolManager
       .generatePoolKey(jdbcURL, jdbcUser, jdbcPassword);

    // Get a connection from the pool for the key that
    // was generated above.  The URL, user, and password
    // passed in case a connection is not available and a
    // new connection must be generated.
    Connection conn = connectionPoolManager.getConnection(
       connectionPoolKey
       , jdbcURL
       , null
       , jdbcUser
       , jdbcPassword);
 

Checking in a connection:

    // Get a connection pool manager instance
    // from the connection pool manager factory
     ConnectionPoolManager connectionPoolManager =
       ConnectionPoolManagerFactory.getConnectionPoolManager();

    // Return the connection to the connection pool.  The target
    // connection pool is identified with the connection pool key
    // that was generated while checking out a connection above.
    // The jdbcConn
     connectionPoolManager.returnConnection(
       mConnectionPoolKey
       , mjdbcConnection);
 

The following guideline should be followed when implementing a custom ConnectionPoolManager:

The connection pool manager should be able to support multiple database instance, user, and password combinations. For more information, see generatePoolKey.

As an example, here is the implementation of the default connection pool manager: public class ConnectionPoolManagerImpl extends ResourcePoolManager implements ConnectionPoolManager { private int mInitPoolSize = 0; private int mMaxPoolSize = 2147483647; public ConnectionPoolManagerImpl() { init(); } private void init() { mInitPoolSize = JboEnvUtil.getPropertyAsInt( PropertyMetadata.ENV_INIT_JDBC_POOL_SIZE.pName , (new Integer(PropertyMetadata.ENV_INIT_JDBC_POOL_SIZE.pDefault)) .intValue()); mMaxPoolSize = JboEnvUtil.getPropertyAsInt( PropertyMetadata.ENV_MAX_JDBC_POOL_SIZE.pName , (new Integer(PropertyMetadata.ENV_MAX_JDBC_POOL_SIZE.pDefault)) .intValue()); } public Connection getConnection( String poolKey , String url , Properties info , String user , String password) { return getConnectionPool(poolKey).getConnection( url , info , user , password); } public Connection getConnectionForInternalUse( String connectionPoolKey , String url , Properties info , String user , String password) { return getConnection(connectionPoolKey, url, info, user, password); } public void addConnection(String poolKey, Connection connection) { getConnectionPool(poolKey).addConnection(connection); } public void returnConnection(String poolKey, Connection connection) { returnConnection(poolKey, connection, null); } public void returnConnection( String poolKey, Connection connection, Properties info) { getConnectionPool(poolKey).returnConnection(connection); } public void returnConnectionForInternalUse( String poolKey, Connection connection, Properties info) { returnConnection(poolKey, connection, info); } public void removeConnection(String poolKey, Connection connection) { getConnectionPool(poolKey).removeConnection(connection); } public String generatePoolKey(String url, Properties info) { String poolKey = url; String user = null; String password = null; if ((info != null) && ((user = (String)info.get(ConnectionCredentials.USER)) != null) && ((password = (String)info.get(ConnectionCredentials.PASSWORD)) != null)) { poolKey = generatePoolKey(url, user, password); } return poolKey; } public String generatePoolKey(String url, String user, String password) { String poolKey = url; if ((user != null) && (password != null)) { poolKey = (new StringBuffer(128)) .append(poolKey) .append(":") .append(user) .append("/") .append(password).toString(); } return poolKey; } public int getInitPoolSize() { return mInitPoolSize; } public int getMaxPoolSize() { return mMaxPoolSize; } protected int getMonitorSleepInterval() { return JboEnvUtil.getPropertyAsInt( PropertyMetadata.ENV_JDBC_POOL_MONITOR_SLEEP_INTERVAL.pName , Integer.valueOf( PropertyMetadata.ENV_JDBC_POOL_MONITOR_SLEEP_INTERVAL.pDefault) .intValue()); } private ConnectionPool getConnectionPool(String poolKey) { ConnectionPool connectionPool = null; synchronized (mLock) { connectionPool = (ConnectionPool)getResourcePool(poolKey); if (connectionPool == null) { connectionPool = new ConnectionPool(poolKey, this); addResourcePool(poolKey, connectionPool); } } return connectionPool; } } which will be loaded if a custom connection pool manager is not specified.

Declaring the custom connection pool manager to the VM

If you are using a custom connection pool manager, you must declare it, either in the jboserver.properties file or as a JVM parameter: For example, to declare the default connection pool manager as a JVM parameter, enter:

java -Djbo.ConnectionPoolManager=oracle.jbo.server.ConnectionPoolManagerImpl

The synonymous command in the jboserver.properties file would be:

jbo.ConnectionPoolManager=oracle.jbo.server.ConnectionPoolManagerImpl

About Connection Pooling

In version 3.2 of Business Components for Java, connection pooling is the new default behavior. Instead of one JDBC connection being created for each application module instance, and being destroyed when the instance disconnects, application modules can now reuse a pool of connections. One connection pool is assigned for each connection URL.

How connections are assigned, created, and released

The framework provides a connection pool manager to manage the pool. When a database connection is needed by a top-level application module instance, the following sequence of events occurs:

1. The application module instance asks the connection pool manager for a connection, as specified in the JDBC connection URL.
2. The connection pool manager looks for an available connection in the pool. If there isn't one, it creates one, up to the maximum allowable connections (MaxPoolSize). If it can't create a connection, it waits for one (there is no timeout).
3. When the application module instance disconnects, it goes back to the pool.

There is one connection pool manager for each business logic tier's Java VM. Connections remain in the pool until the Java VM stops running.

See Also:

ConnectionPoolManagerFactory

Method Summary

void	addConnection(java.lang.String poolKey, java.sql.Connection connection) Adds a connection to a connection pool.
java.lang.String	generatePoolKey(java.lang.String url, java.util.Properties info) Generates a unique pool identifier (poolKey) for the specified JDBC URL and JDBC driver properties.
java.lang.String	generatePoolKey(java.lang.String url, java.lang.String user, java.lang.String password) Generates a unique pool identifier (poolKey) for the specified JDBC URL and JDBC driver properties.
java.sql.Connection	getConnection(java.lang.String connectionPoolKey, java.lang.String url, java.util.Properties info, java.lang.String user, java.lang.String password) Returns a pooled connection from the specified target pool.
java.sql.Connection	getConnectionForInternalUse(java.lang.String connectionPoolKey, java.lang.String url, java.util.Properties info, java.lang.String user, java.lang.String password) Returns a pooled connection from the specified target pool.
int	getInitPoolSize() Returns the initial pool size for connection pools that are managed by this connection pool manager.
int	getMaxPoolSize() Returns the maximum pool size for connection pools that are managed by this connection pool manager.
void	removeConnection(java.lang.String poolKey, java.sql.Connection connection) Removes a pooled connection from a connection pool.
void	returnConnection(java.lang.String poolKey, java.sql.Connection connection) Deprecated. This method has been replaced with returnConnection(String, Connection, Properties). This was necessary to provide applications with additional information about the transaction which is returning the connection.
void	returnConnection(java.lang.String poolKey, java.sql.Connection connection, java.util.Properties info) Returns a pooled connection to a connection pool.
void	returnConnectionForInternalUse(java.lang.String poolKey, java.sql.Connection connection, java.util.Properties info) Returns a pooled connection to a connection pool.

Method Detail

getConnection

public java.sql.Connection getConnection(java.lang.String connectionPoolKey,
                                         java.lang.String url,
                                         java.util.Properties info,
                                         java.lang.String user,
                                         java.lang.String password)

Returns a pooled connection from the specified target pool.

Parameters:

connectionPoolKey - a unique identifier for the target connection pool.

url - the JDBC url that will be used to create connections in this pool.

info - the JDBC properties that will be used to create connections in this pool.

user - the username that will be used for database authentication.

password - the password that will be used for database authentication.

See Also:

generatePoolKey(String, Properties)

getConnectionForInternalUse

public java.sql.Connection getConnectionForInternalUse(java.lang.String connectionPoolKey,
                                                       java.lang.String url,
                                                       java.util.Properties info,
                                                       java.lang.String user,
                                                       java.lang.String password)

Returns a pooled connection from the specified target pool. This method is invoked when the BC4J framework requires a JDBC connection instance for internal use. The method is provided for applications with special handling requirements for internal connections. Internal connections may be required by BC4J to support the failover and spill to disk features of the BC4J framework. Most applications may delegate the implementation of this method to getConnection(String, String, Properties, String, String)

Parameters:

connectionPoolKey - a unique identifier for the target connection pool.

url - the JDBC url that will be used to create connections in this pool.

info - the JDBC properties that will be used to create connections in this pool.

user - the username that will be used for database authentication.

password - the password that will be used for database authentication.

See Also:

generatePoolKey(String, Properties)

returnConnection

public void returnConnection(java.lang.String poolKey,
                             java.sql.Connection connection)

Deprecated. This method has been replaced with returnConnection(String, Connection, Properties). This was necessary to provide applications with additional information about the transaction which is returning the connection.

Returns a pooled connection to a connection pool. The poolKey is used by the connection pool manager to identify the target connection pool.

The implementation of this operation should ensure that the returned connection does in fact belong to the specified connection pool.

Parameters:

poolKey - a unique identifier for the target connection pool.

connection - the connection that should be checked in.

Since:

5.0

See Also:

generatePoolKey(String, Properties)

returnConnection

public void returnConnection(java.lang.String poolKey,
                             java.sql.Connection connection,
                             java.util.Properties info)

Returns a pooled connection to a connection pool. The poolKey is used by the connection pool manager to identify the target connection pool.

The implementation of this operation should ensure that the returned connection does in fact belong to the specified connection pool.

The properties object that is passed to return connection may be used by custom connection pool managers that require the original JDBC context to return the connection to the appropriate pool.

Parameters:

poolKey - a unique identifier for the target connection pool.

connection - the connection that should be checked in.

info - the JDBC context that was used when the connection was acquired.

See Also:

generatePoolKey(String, Properties)

returnConnectionForInternalUse

public void returnConnectionForInternalUse(java.lang.String poolKey,
                                           java.sql.Connection connection,
                                           java.util.Properties info)

Returns a pooled connection to a connection pool. The poolKey is used by the connection pool manager to identify the target connection pool.

The implementation of this operation should ensure that the returned connection does in fact belong to the specified connection pool.

The properties object that is passed to return connection may be used by custom connection pool managers that require the original JDBC context to return the connection to the appropriate pool.

This method is invoked when the BC4J framework is releasing a JDBC connection instance which was used internally. The method is provided for applications with special handling requirements for internal connections. Internal connections may be required by BC4J to support the failover and spill to disk features of the BC4J framework. Most applications may delegate the implementation of this method to returnConnection(String, Connection, Properties).

Parameters:

poolKey - a unique identifier for the target connection pool.

connection - the connection that should be checked in.

info - the JDBC context that was used when the connection was acquired.

See Also:

generatePoolKey(String, Properties)

addConnection

public void addConnection(java.lang.String poolKey,
                          java.sql.Connection connection)

Adds a connection to a connection pool. The poolKey is used by the connection pool manager to identify the target connection pool.

The implementation of this method should not return the connection to the pool after the connection has been added, because the invoking object still holds a reference to that connection. Instead, it is recommended that returning the new connection be the responsibility of of the object that owns the initial reference to the connection.

Parameters:

poolKey - a unique identifier for the target connection pool.

connection - the connection that should be checked in.

See Also:

returnConnection(String, Connection), generatePoolKey(String, Properties)

removeConnection

public void removeConnection(java.lang.String poolKey,
                             java.sql.Connection connection)

Removes a pooled connection from a connection pool. The poolKey is used by the connection pool manager to identify the target connection pool.

Parameters:

poolKey - a unique identifier for the target connection pool.

connection - the connection that should be checked in.

See Also:

generatePoolKey(String, Properties)

generatePoolKey

public java.lang.String generatePoolKey(java.lang.String url,
                                        java.util.Properties info)

Generates a unique pool identifier (poolKey) for the specified JDBC URL and JDBC driver properties. The connection pool manager may be responsible for managing multiple pool instances for each database instance, user, and password combination.

Parameters:

url - the JDBC url that will be used to create connections in this pool.

info - the JDBC properties that will be used to create connections in this pool.

Returns:

a unique pool identifier as a String.

generatePoolKey

public java.lang.String generatePoolKey(java.lang.String url,
                                        java.lang.String user,
                                        java.lang.String password)

Generates a unique pool identifier (poolKey) for the specified JDBC URL and JDBC driver properties. The connection pool manager may be responsible for managing multiple pool instances for each database instance, user, and password combination.

Parameters:

url - the JDBC url that will be used to create connections in this pool.

user - the user that will be used for database authentication.

password - the password that will be used for database authentication.

Returns:

a unique pool identifier as a String.

getMaxPoolSize

public int getMaxPoolSize()

Returns the maximum pool size for connection pools that are managed by this connection pool manager. A maximum pool size of 0 is used by the database transaction class to indicate that pooling has not been enabled.

The MaxPoolSize is typically set as a JVM parameter (for example, java -Djbo.maxpoolsize=10 myApplication note that lower case for the JVM parameter is required) or in the jboserver.properties file (for example, jbo.MaxPoolSize=10 myApplication).

The maximum number of connections supported by a particular driver should be documented with the driver. The default MaxPoolSize is set high enough so that the driver's maximum number of connections will be reached before the default MaxPoolSize is reached.

Returns:

the maximum pool size for this connection pool manager's connection pools.

getInitPoolSize

public int getInitPoolSize()

Returns the initial pool size for connection pools that are managed by this connection pool manager.

The InitPoolSize is typically set as a JVM parameter (for example, java -Djbo.initpoolsize=2 myApplication note that lower case for the JVM parameter is required) or in the jboserver.properties file (for example, jbo.InitPoolSize=2 myApplication).

Returns:

the initial pool size for this connection pool manager's connection pools.