Proactive insights, news and tips from Oracle WebLogic Server Support. Learn Oracle from Oracle.

Connection Initialization Callback on WLS Datasource

Stephen Felts

WebLogic Server is now available. You can see the blog article announcing it at Oracle
WebLogic Server is Now Available.

One of the WLS datasource features that appeared quite a while ago but not mentioned much is the ability to define a callback that is called during connection initialization.  The original intent of this callback was to provide a mechanism that is used with the Application Continuity (AC) feature.  It allows for the application to ensure that the same initialization of the connection can be done when it is reserved and also later on if the connection is replayed.  For the latter case, the original connection has some type of "recoverable" error and is closed, a new connection is reserved under the covers, and all of the operations that were done on the original connection are replayed on the new connection.  The callback allows for the connection to be re-initialized with whatever state is needed by the application.

The concept of having a callback to allow for the application to initialize all connections without scattering this processing all over the application software wherever getConnection() is called is very useful, even without replay being involved.  In fact, since the callback can be configured in the datasource descriptor, which I recommend, there is no change to the application except to write the callback itself.  

Here's the history of support for this feature, assuming that the connection initialization callback is configured.

WLS 10.3.6 - It is only called on an Active GridLink datasource when running with the replay driver (replay was only supported with AGL).

WLS  12.1.1, 12.1.2, and 12.1.3 - It is called if used with the replay driver and any datasource type (replay support was added to GENERIC datasources).

WLS 12.2.1 - It is called with any Oracle driver and any datasource type. 

WLS - It is called with any driver and any datasource type.  Why limit the goodness to just the Oracle driver?

The callback can be configured in the application by registering it on the datasource in the Java code. You need to ensure that you only do this once per datasource.  I think it's much easier to register it in the datasource configuration.   

Here's a sample callback.

package demo;
import oracle.ucp.jdbc.ConnectionInitializationCallback;

public class MyConnectionInitializationCallback implements
  ConnectionInitializationCallback {
  public MyConnectionInitializationCallback()  {
  public void initialize(java.sql.Connection connection)
    throws java.sql.SQLException {
     // Re-set the state for the connection, if necessary

This is a simple Jython script using as many defaults as possible to just show registering the callback.

import sys, socket
hostname = socket.gethostname()
jdbcSR = create(dsname, 'JDBCSystemResource')
jdbcResource = jdbcSR.getJDBCResource()
dsParams = jdbcResource.getJDBCDataSourceParams()
driverParams = jdbcResource.getJDBCDriverParams()
driverProperties = driverParams.getProperties()
userprop = driverProperties.createProperty('user')
oracleParams = jdbcResource.getJDBCOracleParams()
oracleParams.setConnectionInitializationCallback('demo.MyConnectionInitializationCallback')  # register the callback

 Here are a few observations.  First, to register the callback using the configuration, the class must be in your classpath.  It will need to be in the server classpath anyway to run but it needs to get there earlier for configuration.  Second, because of the history of this feature, it's contained in the Oracle parameters instead of the Connection parameters; there isn't much we can do about that.  In the WLS administration console, the entry can be seen and configured in the Advanced parameters of the Connection Pool tab as shown in the following figure (in addition to the Oracle tab).  Finally, note that the interface is a Universal Connection Pool (UCP) interface so that this callback can be shared with your UCP application (all driver types are supported starting in Database

This feature is documented in the Application continuity section of the Administration Guide.   See http://docs.oracle.com/middleware/12211/wls/JDBCA/ds_oracledriver.htm#CCHFJDHF .

You might be disappointed that I didn't actually do anything in the callback.  I'll use this callback again in my next blog to show how it's used in another new WLS feature.

Join the discussion

Comments ( 1 )
  • madhav Thursday, October 20, 2016

    I am feeling lucky to have this ability now in WLS.Great update.

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha

Integrated Cloud Applications & Platform Services