7 Implicit Connection Caching

Turning Caching On

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

Here is a simple example using 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

For details on the connection cache API, see the Javadoc for OracleDataSource and OracleConnectionCacheManager.

Opening a Connection

After you have turned connection caching on, whenever you retrieve a connection through an 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, a logical connection is returned wrapping the physical connection. If no physical connection match is found, 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 sorts of connections the cache may return. The non-cache-specific getConnection() methods behave as normal.

The connection-cache-specific variations are:

• getConnection(java.util.Properties cachedConnectionAttributes)—requests a database connection that matches the specified cachedConnectionAttributes (see "Other Properties" for a discussion of connection attributes)

• getConnection(java.lang.String user, java.lang.String passwd, java.util.Properties cachedConnectionAttributes)—requests a database connection from the Implicit Connection Cache that matches the specified user, passwd and cachedConnectionAttributes

Setting Connection Cache Name

You can specify the connection cache's name by invoking setConnectionCacheName().

Setting Connection Cache Properties

You can fine-tune the behavior of the Implicit Connection cache using the setConnectionCacheProperties() method to set various connection properties. These properties are documented in "Connection Cache Properties" .

Closing A Connection

An application returns a connection to the cache by invoking close(). There are two variants on the close method: one with no arguments, and one that takes a connection attribute argument, discussed in "Setting Connection Attributes" .

Implicit Connection Cache Example

Example 7-2 demonstrates creating a datasource, setting its caching and datasource 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();

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 those connections by attribute using the specialized forms of getConnection:

• getConnection(java.util.Properties cachedConnectionAttributes)—requests a database connection that matches the specified cachedConnectionAttributes

• getConnection(java.lang.String user, java.lang.String passwd, java.util.Properties cachedConnectionAttributes)—requests a database connection from the Implicit Connection Cache that matches the specified user, passwd and cachedConnectionAttributes. If null values are passed for user and password, the DataSource defaults are used.

The rules for what constitutes an attribute match are discussed in the next section.

Setting Connection Attributes

An application sets connection attributes using one of two methods:

• applyConnectionAttributes(java.util.Properties connAttr)

  No validation is done on connAttr. Applying connection attributes is cumulative: each time you invoke applyConnectionAttributes, the connAttr you supply are added to those previously in force.

• close((java.util.Properties connAttr)

  This obliterates the attributes of the specified connection and replaces them with the attributes found in connAttr.

Checking a Returned Connection's Attributes

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, since 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 method java.util.Properties getUnMatchedConnectionAttributes(), 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.

Connection Attribute Example

Example 7-3 illustrates using connection attributes.

java.util.Properties connAttr = new java.util.Properties();
    connAttr.setProperty("TRANSACTION_ISOLATION", "SERIALIZABLE");
    connAttr.setProperty("CONNECTION_TAG", "JOE'S_CONNECTION");
 
    // 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);

Limit Properties

These properties control the size of the cache.

Timeout Properties

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

Other Properties

These properties control miscellaneous cache behaviors.

Connection Property Example

Example 7-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

createCache

This method exists in two signature variants:

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

  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, 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
  
  

  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.

removeCache

void removeCache(String cacheName, int timeout)

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 (similar to TimeToLive timeout) without waiting for the connections in-use to be done. When invoked 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.

reinitializeCache

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

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.

existsCache

boolean existsCache(String CacheName)

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.

enableCache

void enableCache(String cacheName)

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

disableCache

void disableCache(String cacheName)

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.

refreshCache

void refreshCache(String cacheName, int mode)

Refreshes the cache specified by cacheName. There are two modes supported, REFRESH_INVALID_CONNECTIONS and REFRESH_ALL_CONNECTIONS. When invoked with REFRESH_INVALID_CONNECTIONS, each Connection in the cache is checked for validity. If an invalid Connection is found, that connection's resources are removed and replaced with a new Connection. The test for validity is basically a simple query to the dual table: select 1 from dual. When invoked with REFRESH_ALL_CONNECTIONS, all available connections in the cache are closed and replaced with new valid physical connections.

purgeCache

void  purgeCache(String cacheName, boolean cleanupCheckedOutConnections)

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, only the available connections are cleaned up.

getCacheProperties

java.util.properties getCacheProperties(String cacheName)

Retrieves the cache properties for the specified cacheName.

getCacheNameList

String[] getCacheNameList()

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.

getNumberOfAvailableConnections

int getNumberOfAvailableConnections(String cacheName)

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.

getNumberOfActiveConnections

int getNumberOfActiveConnections(String cacheName)

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.

setConnectionPoolDataSource

void setConnectionPoolDataSource(String cacheName, ConnectionPoolDataSource ds)

Allows 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.

Example Of ConnectionCacheManager Use

Example 7-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);

Attribute Weights And Connection Matching

There are two connection cache properties that allow the developer to specify which connections in the connection cache are accepted in response to agetConnection() 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.

Connection Cache Callbacks

The implicit connection cache offers a way for the application to specify callbacks to be invoked by the connection cache. Callback methods are supported with the OracleConnectionCacheCallback interface. This callback mechanism is useful to take advantage of the application's special knowledge of 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's 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 invoked. The cbkflag parameter specifies which callback method should be invoked. 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 invoked. 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 callback's handleAbandonedConnection() before reclaiming the connection. If the callback returns true, the connection is reclaimed. If the callback returns false, the connection remains active. For details, see "Connection Cache Manager API" .

The UserConnectionCacheCallback interface supports two callback methods to be implemented by the user, releaseConnection() and handleAbandonedConnection(). For details on these methods, see the Javadoc.