To understand this sample the user is expected to have
the following skills,
JDBC
Technical Overview
The implicit connection cache provides a mechanism for users
to define cache behavior when a connection is returned to the cache. When a
callback is registered on an OracleConnection, 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. 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 before getting
the connection from the cache. The registration can be done using the OracleConnection
as,
registerConnectionCacheCallback( OracleConnectionCacheCallback callbackImpl, Object userObj, int callbackFlag )
In this interface, callbackImpl is the user's implementation
of the OracleConnectionCacheCallback interface. The userObj parameter contains
any parameters that the user wants supplied. This user object is passed back,
unmodified, when the callback method is invoked. The callbackFlag parameter
specifies which callback method should be invoked. It must be one of the following
values:
OracleConnection.ABANDONED_CONNECTION_CALLBACK - calls only handleAbandonedConnection() method OracleConnection.RELEASE_CONNECTION_CALLBACK - calls only releaseConnection() method OracleConnection.ALL_CALLBACKS - calls all connection cache callback methods
For example, you can register a callback, to invoke all callback methods as
below,
((OracleConnection)conn).registerConnectionCacheCallback( new UserConnectionCacheCallback(),
new SomeUserObject(),
OracleConnection.ALL_CALLBACKS);
The following section explains the working of callback
methods:
handleAbandonedConnection()
public boolean handleAbandonedConnection(OracleConnection conn, Object userObj)
This callback method works in conjunction with the connection
cache property, AbandonedConnectionTimeout, and overrides the default cache behavior.
If the callback is registered, the handleAbandonedConnection() method is called
overriding the default behavior, while the AbandonedConnectionTimeout property
is processed. The user of this callback method decides on how to handle the connection
that has not had no database calls for the specified period of time. There can
be two outcomes:
User decides to hold on to the connection longer,
even though the the connection is inactive for the specified time. The callback
method returns false
in this case.
User decides to handle the connection and does the
necessary cleanup and close. The callback method returns true
in this case.
releaseConnection()
public void releaseConnection(OracleConnection conn, Object userObj)
If releaseConnection() callback is registered on a connection,
and the cache from which the connection was retrieved is empty, the connection
cache waits for the user to release a connection back to the cache, by closing
the logical connection. The releaseConnection()
callback method is useful, when the user wants to override this default behavior.
This method works in conjunction with release priorities set on the logical connection.
A setter and getter method is provided on the connection object to set the connection
release priorities. They are,
public void setReleasePriority(int priority);
public int getReleasePriority();
The release priorities, declared as static finals on the connection object, are:
If releaseConnection() callback is registered on a connection,
and the cache from which the connection was retrieved is empty, then instead of
the default behavior to wait for connections to be returned to the cache, the
following actions take place:
For every connection, that has the release priority set to high, invoke
the callback method.
Check the cache if the number of connections released to the cache are
below the lower cache threshold limit. LowerThresholdLimit is a connection
cache property that may be optionally set. Default value is 20% of the MaxLimit.
If the lower threshold limit has not reached, even after all the high release
priority connections are processed, then the low release priority connections
are processed.
Cache stops calling the releaseConnection() callback method, either when
the cache reaches connections above the lower threshold limit, or when all
the high and low release priority connections have been processed once.
Connections that have the release priority set to locked are skipped.
Application
Overview
This application is designed to show how to implement the connection
cache callback mechanism in an application. This sample application has three
classes namely CacheManager, EmpManager and the CallbackHandler. The CacheManager
class is used to create and manage a connection cache. The EmpManager class
gets the connection from the connection cache using the CacheManager and displays
the data from he EMP table. This class extends the java.lang.Thread class to
enable running multiple threads concurrently. Each thread is given a certain
amount of delay, to show how the callback mechanism works when the connections
become inactive. The CallbackHandler class implements the OracleConnectionCacheCallback
interface.
When the cache is created, three important properties, the PropertyCheckInterval,
AbandonedConnectionTimeout and LowerThresholdLimit
are set. PropertyCheckInterval sets the time interval at which the cache manager
inspects and enforces all specified cache properties. The AbandonedConnectionTimeout
specifies the maximum time that a connection can remain inactive before the
connection is closed and returned to the cache. A connection is considered inactive
if it has not had any SQL database activity. When the connection becomes inactive
the connection is reclaimed and returned to the cache for reuse. When the application
registers a ConnectionCacheCallback on the connection, the cache calls the callback's
handleAbondonedConnection() before reclaiming the connection. And the LowerThresholdLimit
sets the lower threshold limit on the cache. The default is 20% of the MaxLimit
on the connection cache. This property is used when releaseConnection() cache
callback method is registered.
This sample application runs five threads which access the database. The display
method in the EmpManager class executes the SELECT statement on the EMP table
and displays the employee names. For threads 'three' and 'four' a time delay
of two and three seconds, respectively, is set in the display() method. This
delay makes the connection inactive, after the execution of SELECT statement.
This time delay is greater or equal to the value set for AbandonedConnectionTimeout
in the connection cache. The PropertyCheckInterval
is set for two seconds which means that, for every two seconds the connection
cache inspects all the specified connection properties. Whenever the cache finds
an inactive connection it calls the handleAbandonedConnection()
method of the CallbackHandler class, which implements the OracleConnectionCacheCallback
interface. This method closes the connection and sets a boolean flag in the
application to indicate closure of the inactive connection.
When the thread 'five' tries to access the database, the cache would have been
empty or the number of connections in the cache would have reached the LowerThresholdLimit.
Since a callback had been registered, the cache calls the releaseConnection()
method of the CallbackHandler. This method closes the connection used by one
of the threads and releases it back to the cache. Thus thread 'five' continues
to get the connection and accesses the database normally.
Software Requirements
Following softwares are required for configuring and running
this sample application.
The directory where Oracle Database 10g is installed
<JAVA_HOME>
The directory where J2SE SDK1.4.x is installed
Configuring the
Application
Download the CacheCallbackSample.jar.
Extract it into <SAMPLE_HOME> folder by executing the following command,
jar xvf CacheCallbackSample.jar
This creates a folder CacheCallbackSample, which contains all the source files.
From the <SAMPLE_HOME>/CacheCallbackSample/config
folder, open Connection.properties in the text editor. Edit the HostName,
SID, Port, UserName and Password fields to match your database details.
Note:You will find jar.exe in <JAVA_HOME>\bin.
Ensure <JAVA_HOME>\bin is present in your system path.
Deploying and Running
the Application
The application can be deployed and run in either of the following
ways:
From the <SAMPLE_HOME>/CacheCallbackSample
folder, open the CacheCallbackSample.jws using Oracle JDeveloper 10g.
Select CacheCallback project from the 'Applications Navigator'.
Right click on 'CacheCallback' project and select
'Project Properties'->'Libraries'. Under the 'Selected Libraries', edit
JDBC10g to add the ojdbc14.jar in the classpath.
Right click on CacheCallback project and Run the application.
Run the Application
using JDK
Following steps explain how to run the application using the
command prompts on different platforms.
Running on Windows
Open the command prompt. Change the current working
directory to <SAMPLE_HOME>/CacheCallbackSample/src
Example : cd d:/otnsamples/CacheCallbackSample/src
Set the CLASSPATH to include Oracle JDBC Driver file (ojdbc14.jar)
and the <SAMPLE_HOME>/CacheCallbackSample/config folder
Example : set CLASSPATH=d:/oracle10g/jdbc/lib/ojdbc14.jar;d:/otnsamples/CacheCallbackSample/config;.;
Compile the Java source files using javac
javac oracle/otnsamples/jdbc10g/*.java
Run the class file using Java command
java oracle.otnsamples.jdbc10g.EmpManager
Note: ojdbc14.jar is available under <ORACLE_HOME>/jdbc/lib
folder
Running on Linux
Open the command prompt. Change the working directory
to <SAMPLE_HOME>/CacheCallbackSample/src
Example : CD /home/otnsamples/CacheCallbackSample/src
Set CLASSPATH to include Oracle JDBC Driver file (ojdbc14.jar)
and the <SAMPLE_HOME>/CacheCallbackSample/config folder
Example : export CLASSPATH=/home/OracleHOme/jdbc/lib/ojdbc14.jar:/home/otnsamples/CacheCallbackSample/config:.
Compile the Java source files using javac command
javac oracle/otnsamples/jdbc10g/*Java
Run the class file using Java command
java oracle.otnsamples.jdbc10g.EmpManager
Note: ojdbc14.jar is available
under <ORACLE_HOME>/jdbc/lib folder
Sample Application
Files
This section will provide a tabular listing of the sample
application files available under CacheCallbackSample folder, along with their
respective directory locations and a description of their role in the overall
scheme of the application.
Directory
File
Description
doc
Readme.html
This file
config
Connection.properties
The properties file which contains database
connection details
src/oracle/otnsamples/jdbc10g
CacheManager.java
This Java source files is used to create
and maintain the connection cache
src/oracle/otnsamples/jdbc10g
CallbackHandler.java
The connection cache callback implementation
class
src/oracle/otnsamples/jdbc10g
EmpManager.java
The main class in the sample
that uses the connection cache
Bookmark
