23 Implicit Connection Caching

23.2.1 Turning Caching On

An application turns the implicit connection cache on by calling OracleDataSource.setConnectionCachingEnabled(true). After implicit caching is turned on, the first connection request to the OracleDataSource transparently creates a connection cache.

Example 23-1 provides a sample code that uses the implicit connection cache.

// Example to show binding of OracleDataSource to JNDI,
// then using implicit connection cache 
 
import oracle.jdbc.pool.*; // import the pool package
 
Context ctx = new InitialContext(ht);
OracleDataSource ods = new OracleDataSource();
 
// Set DataSource properties
ods.setUser("Scott");
ods.setConnectionCachingEnabled(true);    // Turns on caching
ctx.bind("MyDS", ods);
// ...
// Retrieve DataSource from the InitialContext
ods =(OracleDataSource) ctx. lookup("MyDS");  
 
// Transparently create cache and retrieve connection 
conn = ods.getConnection();
// ...
conn.close();  // return connection to the cache
// ...
ods.close() // close datasource and clean up the cache

23.2.2 Opening a Connection

After you have turned connection caching on, whenever you retrieve a connection through OracleDataSource.getConnection, the JDBC drivers check to see if a connection is available in the cache.

The getConnection method checks if there are any free physical connections in the cache that match the specified criteria. If a match is found, then a logical connection is returned wrapping the physical connection. If no physical connection match is found, then a new physical connection is created, wrapped in a logical connection, and returned.

There are four variations on getConnection, two that make no reference to the connection cache and two that specify which sort of connections the cache may return. The non-cache-specific getConnection methods behave as normal.

23.2.3 Setting Connection Cache Name

The ConnectionCacheName property of OracleDataSource is an optional property used by the Connection Cache manager to manage a connection cache. You can set this property by calling the following method:

public void synchronized setConnectionCacheName(String cacheName) throws SQLException

When this property is set, the name is used to uniquely identify the cache accessed by the cache-enabled OracleDataSource. If the property is not set, then a default cache name is created using the convention DataSourceName#HexRepresentationOfNumberOfCaches.

23.2.4 Setting Connection Cache Properties

You can fine-tune the behavior of the implicit connection cache using the setConnectionCacheProperties method to set various connection properties.

23.2.5 Closing A Connection

An application returns a connection to the cache by calling close. There are two variants of the close method: one with no arguments and one that takes a Connection object as argument.

23.2.6 Implicit Connection Cache Example

Example 23-2 demonstrates creating a data source, setting its caching and data source properties, retrieving a connection, and closing that connection in order to return it to the cache.

import java.sql.*;
import javax.sql.*;
import java.util.*;
import javax.naming.*;
import javax.naming.spi.*;
import oracle.jdbc.*;
import oracle.jdbc.pool.*;

...
      // create a DataSource    OracleDataSource ods = new OracleDataSource();    // set cache properties    java.util.Properties prop = new java.util.Properties();    prop.setProperty("MinLimit", "2");    prop.setProperty("MaxLimit", "10");    // set DataSource properties    String url = "jdbc:oracle:oci8:@";    ods.setURL(url);    ods.setUser("hr");    ods.setPassword("hr");    ods.setConnectionCachingEnabled(true); // be sure set to true    ods.setConnectionCacheProperties (prop);    ods.setConnectionCacheName("ImplicitCache01"); // this cache's name 
 
    // We need to create a connection to create the cache 
    Connection conn = ds.getConnection(user, pass);
    Statement  stmt  = conn1.createStatement();
    ResultSet  rset  = stmt.executeQuery("select user from dual");
    conn1.close(); 
 
    ods.close();

23.3.1 Getting Connections

The first connection you retrieve has no attributes. You must set them. After you have set attributes on a connection, you can request the connection by specifying its attribute, using the specialized forms of getConnection:

• getConnection(java.util.Properties cachedConnectionAttributes

  Requests a database connection that matches the specified cachedConnectionAttributes.

  
  

  See Also: For a discussion on connection attributes, see "Other Properties" .

  
  

• getConnection(java.lang.String user, java.lang.String password, java.util.Properties cachedConnectionAttributes)

  Requests a database connection from the implicit connection cache that matches the specified user, password and cachedConnectionAttributes. If null values are passed for user and password, the DataSource defaults are used.

Attribute Matching Rules

The rules for matching connectionAttributes come in two variations:

• Basic

  In this, the cache is searched to retrieve the connection that matches the attributes. The connection search mechanism as follows:

  1. If an exact match is found, the connection is returned to the caller.

  2. If an exact match is not found and the ClosestConnectionMatch data source property is set, then the connection with the closest match is returned. The closest matched connection is one that has the highest number of the original attributes matched. Note that the closest matched connection may match a subset of the original attributes, but does not have any attributes that are not part of the original list. For example, if the original list of attributes is A, B and C, then a closest match may have A and B set, but never a D.

  3. If none of the existing connections match, a new connection is returned. The new connection is created using the user name and password set on the DataSource. If getConnection(String, String, java.util.Properties) is called, then the user name and password passed as arguments are used to open the new connection.

• Advanced, where attributes may be associated with weights. The connection search mechanism is similar to the basic connectionAttributes based search, except that the connections are searched not only based on the connectionAttributes, but also using a set of weights that are associated with the keys on the connectionAttributes. These weights are assigned to the keys as a one time operation and is supported as a connection cache property, AttributeWeights.

23.3.2 Setting Connection Attributes

An application sets connection attributes using:

applyConnectionAttributes(java.util.Properties connAttr)

No validation is done on connAttr. Applying connection attributes is cumulative. Each time you call applyConnectionAttributes, the connAttr attribute you supply is added to those previously in force.

23.3.3 Checking Attributes of a Returned Connection

When an application requests a connection with specified attributes, it is possible that no match will be found in the connection cache. When this happens, the connection cache creates a connection with no attributes and returns it. The connection cache cannot create a connection with the requested attributes, because the cache manager is ignorant of the semantics of the attributes.

For this reason, applications should always check the attributes of a returned connection. To do this, use the getUnMatchedConnectionAttributes method, which returns a list of any attributes that were not matched in retrieving the connection. If the return value of this method is null, you know that you must set all the connection attributes.

23.3.4 Connection Attribute Example

Example 23-3 illustrates using connection attributes.

java.util.Properties connAttr = new java.util.Properties();
    connAttr.setProperty("connection_type", "payroll");
 
    // retrieve connection that matches attributes
    Connection conn = ds.getConnection(connAttr); 
    // Check to see which attributes weren't matched
   unmatchedProp = ((OracleConnection)conn).getUnMatchedConnectionAttributes();
   if ( unmatchedProp != null )
    {
    // apply attributes to the connection
    ((OracleConnection)conn).applyConnectionAttributes(connAttr);  
    }
    // verify whether conn contains property after apply attributes
    connProp = ((OracleConnection)conn).getConnectionAttributes(); 
    listProperties (connProp);

23.4.1 Limit Properties

These properties control the size of the cache.

InitialLimit

Sets how many connections are created in the cache when it is created or reinitialized. When this property is set to an integer value greater than 0, creating or reinitializing the cache automatically creates the specified number of connections, filling the cache in advance of need.

Default: 0

MaxLimit

Sets the maximum number of connection instances the cache can hold. The default value is Integer.MAX_VALUE, meaning that there is no limit enforced by the connection cache, so that the number of connections is limited only by the number of database sessions configured for the database.

Default: Integer.MAX_VALUE (no limit)

MaxStatementsLimit

Sets the maximum number of statements that a connection keeps open. When a cache has this property set, reinitializing the cache or closing the data source automatically closes all cursors beyond the specified MaxStatementsLimit.

Default: 0

MinLimit

Sets the minimum number of connections the cache maintains. This guarantees that the cache will not shrink below this minimum limit.

Default: 0

23.4.2 TIMEOUT Properties

These properties control the lifetime of an element in the cache.

InactivityTimeout

Sets the maximum time a physical connection can remain idle in a connection cache. An idle connection is one that is not active and does not have a logical handle associated with it. When InactivityTimeout expires, the underlying physical connection is closed. However, the size of the cache is not allowed to shrink below minLimit, if it has been set.

Default: 0 (no timeout in effect)

TimeToLiveTimeout

Sets the maximum time in seconds that a logical connection can remain open. When TimeToLiveTimeout expires, the logical connection is unconditionally closed, the relevant statement handles are canceled, and the underlying physical connection is returned to the cache for reuse.

Default: 0 (no timeout in effect)

AbandonedConnectionTimeout

Sets the maximum time that a connection can remain unused before the connection is closed and returned to the cache. A connection is considered unused if it has not had SQL database activity.

When AbandonedConnectionTimeout is set, JDBC monitors SQL database activity on each logical connection. For example, when stmt.execute is called on the connection, a heartbeat is registered to convey that this connection is active. The heartbeats are set at each database execution. If a connection has been inactive for the specified amount of time, the underlying connection is reclaimed and returned to the cache for reuse.

Default: 0 (no timeout in effect)

PropertyCheckInterval

Sets the time interval at which the cache manager inspects and enforces all specified cache properties. PropertyCheckInterval is set in seconds.

Default: 900 seconds

23.4.3 Other Properties

These properties control miscellaneous cache behaviors.

AttributeWeights

AttributeWeights sets the weight for each attribute set on the connection.

ClosestConnectionMatch

ClosestConnectionMatch causes the connection cache to retrieve the connection with the closest approximation to the specified connection attributes.

ConnectionWaitTimeout

Specifies cache behavior when a connection is requested and there are already MaxLimit connections active. If ConnectionWaitTimeout is greater than zero, then each connection request waits for the specified number of seconds or until a connection is returned to the cache. If no connection is returned to the cache before the timeout elapses, then the connection request returns null.

Default: 0 (no timeout)

LowerThresholdLimit

Sets the lower threshold limit on the cache. The default is 20 percent of the MaxLimit on the connection cache. This property is used whenever a releaseConnection() cache callback method is registered.

ValidateConnection

Setting ValidateConnection to true causes the connection cache to test every connection it retrieves against the underlying database.

Default: false

23.4.4 Connection Property Example

Example 23-4 demonstrates how an application uses connection properties.

import java.sql.*;
import javax.sql.*;
import java.util.*;
import javax.naming.*;
import javax.naming.spi.*;
import oracle.jdbc.*;
import oracle.jdbc.pool.*;
...
  OracleDataSource ds =  (OracleDataSource) ctx.lookup("...");
  java.util.Properties prop = new java.util.Properties ();
  prop.setProperty("MinLimit", "5");     // the cache size is 5 at least 
  prop.setProperty("MaxLimit", "25");
  prop.setProperty("InitialLimit", "3"); // create 3 connections at startup
  prop.setProperty("InactivityTimeout", "1800");    //  seconds
  prop.setProperty("AbandonedConnectionTimeout", "900");  //  seconds
  prop.setProperty("MaxStatementsLimit", "10");
  prop.setProperty("PropertyCheckInterval", "60"); // seconds

  ds.setConnectionCacheProperties (prop);  // set properties
  Connection conn = ds.getConnection();
  conn.dosomework();
  java.util.Properties propList=ds.getConnectionCacheProperties();  // retrieve

23.5.1 createCache

The createCache method has the following signatures:

• void createCache(String cacheName, javax.sql.DataSource ds, java.util.Properties cacheProps)

  This method creates a new cache identified by a unique cache name. The newly-created cache is bound to the specified DataSource object. Cache properties, when specified, are applied to the cache that gets created. When cache creation is successful, the Connection Cache Manager adds the new cache to the list of caches managed. Creating a cache with a user-defined cache name facilitates specifying more meaningful names. For example, dynamic monitoring service (DMS) metrics collected on a per-cache basis could display metrics attached to a meaningful cache name. createCache throws an exception, if a cache already exists for the DataSource object passed in.

• String createCache(javax.sql.DataSource ds, java.util.Properties cacheProps)

  This method creates a new cache using a generated unique cache name and returns this cache name. The standard convention used in cache name generation is DataSourceName#HexRepresentationOfNumberOfCaches. The semantics are otherwise identical to the previous form.

23.5.2 disableCache

The signature of this method is as follows:

void disableCache(String cacheName)

This method temporarily disables the cache specified by cacheName. This means that, temporarily, connection requests will not be serviced from this cache. However, in-use connections will continue to work uninterrupted.

23.5.3 enableCache

The signature of this method is as follows:

void enableCache(String cacheName)

This method enables a disabled cache. This is a no-op if the cache is already enabled.

23.5.4 existsCache

The signature of this method is as follows:

boolean existsCache(String CacheName)

This method checks whether a specific connection cache exists among the list of caches that the Connection Cache Manager handles. Returns true if the cache exists, false otherwise.

23.5.5 getCacheNameList

The signature of this method is as follows:

String[] getCacheNameList()

This method returns all the connection cache names that are known to the Connection Cache Manager. The cache names may then be used to manage connection caches using the Connection Cache Manager APIs.

23.5.6 getCacheProperties

The signature of this method is as follows:

java.util.properties getCacheProperties(String cacheName)

This method retrieves the cache properties for the specified cacheName.

23.5.7 getNumberOfActiveConnections

The signature of this method is as follows:

int getNumberOfActiveConnections(String cacheName)

This method returns the number of checked out connections, connections that are active or busy, and hence not available for use. The value returned is a snapshot of the number of checked out connections in the connection cache at the time the API was processed. It may become invalid quickly.

23.5.8 getNumberOfAvailableConnections

The signature of this method is as follows:

int getNumberOfAvailableConnections(String cacheName)

This method returns the number of connections in the connection cache, that are available for use. The value returned is a snapshot of the number of connections available in the connection cache at the time the API was processed. It may become invalid quickly.

23.5.9 isFatalConnectionError

The signature of this method is as follows:

boolean isFatalConnectionError(SQLException se)

This method is used to differentiate fatal errors from non-fatal errors and may be used in the exception handling modules of the application to trigger connection retries. Some of the errors that are considered fatal are: ORA-3113, ORA-3114, ORA-1033, ORA-1034, ORA-1089, ORA-1090, and ORA-17002.

23.5.10 purgeCache

The signature of this method is as follows:

void  purgeCache(String cacheName, boolean cleanupCheckedOutConnections)

This method removes connections from the connection cache, but does not remove the cache itself. If the cleanupCheckedOutConnections parameter is set to true, then the checked out connections are cleaned up, as well as the available connections in the cache. If the cleanupCheckedOutConnections parameter is set to false, then only the available connections are cleaned up.

23.5.11 refreshCache

The signature of this method is as follows:

void refreshCache(String cacheName, int mode)

This method refreshes the cache specified by cacheName. There are two modes supported, REFRESH_INVALID_CONNECTIONS and REFRESH_ALL_CONNECTIONS. When called with REFRESH_INVALID_CONNECTIONS, each Connection in the cache is checked for validity. If an invalid Connection is found, then the resources of that connection are removed and replaced with a new Connection. The test for validity is a simple query as follows:

SELECT 1 FROM dual;

When called with REFRESH_ALL_CONNECTIONS, all available connections in the cache are closed and replaced with new valid physical connections.

23.5.12 reinitializeCache

The signature of this method is as follows:

void reinitializeCache(String cacheName, java.util.properties cacheProperties)

This method reinitializes the cache using the specified new set of cache properties. This supports dynamic reconfiguration of caches. The new properties take effect on all newly-created connections, as well as on existing connections that are not in use. When the reinitializeCache method is called, all in-use connections are closed. The new cache properties are then applied to all the connections in the cache.

23.5.13 removeCache

The signature of this method is as follows:

void removeCache(String cacheName, int timeout)

This method removes the cache specified by cacheName. All its resources are closed and freed. The second parameter is a wait timeout value that is specified in seconds. If the wait timeout value is 0, then all in-use or checked out connections are reclaimed without waiting for the connections in-use to be done. When called with a wait timeout value greater than 0, the operation waits for the specified period of time for checked out connections to be closed before removing the connection cache. This includes connections that are closed based on timeouts specified. Connection cache removal is not reversible.

23.5.14 setConnectionPoolDataSource

The signature of this method is as follows:

void setConnectionPoolDataSource(String cacheName, ConnectionPoolDataSource ds)

This method enables connections to be created from an external OracleConnectionPoolDataSource, instead of the default DataSource, for the given connection cache. When such a ConnectionPoolDataSource is set, all DataSource properties, such as url, are derived from this new DataSource.

23.5.15 Example Of ConnectionCacheManager Use

Example 23-5 demonstrates the OracleConnectionCacheManager interfaces.

import java.sql.*;
import javax.sql.*;
import java.util.*;
import javax.naming.*;
import javax.naming.spi.*;
import oracle.jdbc.*;
import oracle.jdbc.pool.*;
...
// Get singleton ConnectionCacheManager instance
  OracleConnectionCacheManager occm =
  OracleConnectionCacheManager.getConnectionCacheManagerInstance();
  String cacheName = "foo";  // Look for a specific cache
  // Use Cache Manager to check # of available connections 
  // and active connections
  System.out.println(occm.getNumberOfAvailableConnections(cacheName)
      " connections are available in cache " + cacheName);
 
  System.out.println(occm.getNumberOfActiveConnections(cacheName)
      + " connections are active");
  // Refresh all connections in cache 
  occm.refreshCache(cacheName,
    OracleConnectionCacheManager.REFRESH_ALL_CONNECTIONS);
  // Reinitialize cache, closing all connections
  java.util.Properties newProp = new java.util.Properties();
  newProp.setProperty("MaxLimit", "50");
  occm.reinitializeCache(cacheName, newProp);

23.6.1 Attribute Weights And Connection Matching

There are two connection cache properties that enable the developer to specify which connections in the connection cache are accepted in response to a getConnection request. When you set the ClosestConnectionMatch property to true, you are telling the connection cache manager to return connections that match only some of the attributes you have specified.

If you do not specify attributeWeights, then the connection cache manager returns the connection that matches the highest number of attributes. If you specify attributeWeights, then you can control the priority the manager uses in matching attributes.

ClosestConnectionMatch

Setting ClosestConnectionMatch to true causes the connection cache to retrieve the connection with the closest approximation to the specified connection attributes. This can be used in combination with AttributeWeights to specify what is considered a closest match.

Default: false

AttributeWeights

Sets the weights for each connectionAttribute. Used when ClosestConnectionMatch is set to true to determine which attributes are given highest priority when searching for matches. An attribute with a high weight is given more importance in determining a match than an attribute with a low weight.

AttributeWeights contains a set of Strings representing key/value pairs. Each key/value pair sets the weights for each connectionAttribute for which the user intends to request a connection. Each String is in the format written by the java.util.Properties.Store(OutputStream, String) method, and thus can be read by the java.util.Properties.load(InputStream) method. The Key is a connectionAttribute and the Value is the weight. A weight must be an integer value greater than 0. The default weight is 1.

For example, TRANSACTION_ISOLATION could be assigned a weight of 10 and ROLE a weight of 5. If ClosestConnectionMatch is set to true, when a connectionAttribute based connection request is made on the cache, connections with a matching TRANSACTION_ISOLATION will be favored over connections with a matching ROLE.

Default: No AttributeWeights

23.6.2 Connection Cache Callbacks

The implicit connection cache offers a way for the application to specify callbacks to be called by the connection cache. Callback methods are supported with the OracleConnectionCacheCallback interface. This callback mechanism is useful to take advantage of the special knowledge of the application about particular connections, supplementing the default behavior when handling abandoned connections or when the cache is empty.

OracleConnectionCacheCallback is an interface that must be implemented by the user and registered with OracleConnection. The registration API is:

public void
registerConnectionCacheCallback(
OracleConnectionCacheCallback cbk, Object usrObj,  int cbkflag);

In this interface, cbk is the user implementation of the OracleConnectionCacheCallback interface. The usrObj parameter contains any parameters that the user wants supplied. This user object is passed back, unmodified, when the callback method is called. The cbkflag parameter specifies which callback method should be called. It must be one of the following values:

• OracleConnection.ABANDONED_CONNECTION_CALLBACK

• OracleConnection.RELEASE_CONNECTION_CALLBACK

• OracleConnection.ALL_CALLBACKS

When ALL_CALLBACKS is set, all the connection cache callback methods are called. For example,

// register callback, to invoke all callback methods
((OracleConnection)conn).registerConnectionCacheCallback( new UserConnectionCacheCallback(), 
  new SomeUserObject(), 
OracleConnection.ALL_CALLBACKS);

An application can register a ConnectionCacheCallback on an OracleConnection. When a callback is registered, the connection cache calls the handleAbandonedConnection method of the callback before reclaiming the connection. If the callback returns true, then the connection is reclaimed. If the callback returns false, then the connection remains active.

The UserConnectionCacheCallback interface supports two callback methods to be implemented by the user, releaseConnection and handleAbandonedConnection.

23.6.3 Use Cases for TimeToLiveTimeout and AbandonedConnectionTimeout

The following are the use cases for the TimeToLiveTimeout and AbandonedConnectionTimeout timeout mechanisms when used with implicit connection cache. Note that these timeout mechanisms are applicable to the logical connection when it is retrieved from the connection cache.

• The application considers the connections are completely stateless

  When the connections are stateless either of the timeout mechanisms can be used. The connections for which the timeout expires are put back into the connection cache for reuse. These connections are valid for reuse because there is no session state associated with them.

• The application maintains state on each connection, but has a cleanup routine that can render the connections stateless when they are returned to the connection cache

  In this case, TimeToLiveTimeout cannot be used. There is no way for the connection cache to ensure that a connection returned to the cache is in a reusable condition.However, AbandonedConnectionTimeout can be used in this scenario, only if OracleConnectionCacheCallback is registered on the connection. The handleAbandonedConnection callback method is implemented by the application and ensures that the necessary cleanup is done. The connection is closed when the timeout processing invokes this callback method. The closing of this connection by the call back method causes the connection to be put back into the connection cache in a state where it is reusable.

  
  

  See Also: "Connection Cache Callbacks"

  
  

• The application maintains state on each connection, but has no control over the connection and, therefore, cannot ensure cleaning up of state for reuse of connections by other applications or users

  The use of either of the timeout mechanism is not recommended.