Sample Illustrating Oracle9i JDBC OCI Transparent Application Failover Callbacks.

Table Of Contents 

• Overview of the Sample Application
• Notations used
• Required Software
• Application Set-up and Configuration
• Running the Application 
• Using Oracle9i JDeveloper 
• From command line
• Description of Sample Files
• Trouble Shooting

Transparent Application Failover (TAF) or simply Application Failover is a feature of the OCI driver. It automatically reconnects to a database if the database instance to which the connection is made goes down. In this case, the active transactions roll back. (A transaction rollback restores the last committed transaction.) The new database connection, though created by a different node, is identical to the original. This is true regardless of how the connection was lost.

 This sample demonstrates the registration and operation of Oracle9i JDBC OCI application failover callbacks by registering a callback function with the connection. The application connects to the database and spawns a thread, which runs for infinite. In this thread, the count of total no of Orders from the Orders table is inserted as a row in the table Order_Data. Then the thread sleeps for 5 second. Now, to demonstrate the Transparent Application Failover (TAF) feature, the database is forcefully shutdown (ABORT).

In this application, the following events are captured    :

• FO_BEGIN: Indicates that failover has detected a lost connection and failover is starting.
• FO_END: Indicates successful completion of failover.
• FO_ABORT: Indicates that failover was unsuccessful and there is no option of retrying.
• FO_REAUTH : indicates that a user handle has been re-authenticated.

Steps in the Sample

Step 1: To demonstrate the functionality, compile and start up the sample.   (as explained  in the below sections)

Step 2: Log into sqlplus and connect /as sysdba.

Step 3: While the sample is still running, shutdown the database with "shutdown abort". At this moment, the failover callback functions will be invoked.

Step 4: The failover events will be captured and the respective messages are displayed.

Step 5: The database can be restarted using "startup", and the interrupted query will be continued.

Here is the code explaining Transaction Failover Call back Function. You can find more details of the code in OCIdriverTAFSample.java file under src\oracle\otnsamples\oracle9ijdbc\ocitaf folder. Look into Description of Sample Files section for folder and file details.

  ....
    // Create an instance of the Callback class with the GUI
    // The failover messages are displayed in the GUI
    cbk = new CallBack(GUI);

    // Store any client information that can be provided when callback method
    // is invoked
    String msg = "OCI TAF Test ";
    try {

      // register TAF callback function
      ((OracleConnection) conn).registerTAFCallback(cbk,msg);				  
  ......
   
   // The OracleOCIFailover interface includes the callbackFn() method,
   // Define the CallBack class
   class CallBack implements OracleOCIFailover {

    ....
    /**
     * There are 3 possible failover types
     *
     *   FO_SESSION     indicates FAILOVER_MODE=SESSION. This means that only the
     *                  user session is re-authenticated on the server-side while
     *                  open cursors in the OCI application need to be re-executed.
     *
     *   FO_SELECT      indicates FAILOVER_MODE=SELECT. Not only the user session
     *                  is re-authenticated on the server-side, but open cursors
     *                  in the OCI can continue fetching.
     *
     *   FO_NONE        indicates FAILOVER_MODE=NONE. This is the default, in which
     *                  no failover functionality is used.
     *
     */
    public int callbackFn (Connection conn,Object ctxt,int type,int event){        
      // Find the Failover Type
      switch (type) {

         case FO_SESSION:
          failoverType = "SESSION";
          break;

        case FO_SELECT:
          failoverType = "SELECT";
          break;

        default:
           failoverType = "NONE";
      }

      /**
       * There are 7 possible failover event
       *
       *   FO_BEGIN  = 1  indicates that failover has detected a
       *                  lost connection and failover is starting.
       *   FO_END    = 2  indicates successful completion of failover.
       *   FO_ABORT  = 3  indicates that failover was unsuccessful,
       *                  and there is no option of retrying.
       *   FO_REAUTH = 4  indicates that a user handle has been re-authenticated.
       *   FO_ERROR  = 5  indicates that failover was temporarily un-
       *                  successful, but it gives the application the opportunity
       *                  to handle the error and retry failover.
       *                  The usual method of error handling is to issue
       *                  sleep() and retry by returning the value FO_RETRY
       *   FO_RETRY  = 6  retry failover
       *   FO_EVENT_UNKNOWN = 7  It is a bad failover event
       **/

       // Find the Failover Event
       switch (event) {	
          // handle the event here
          .....
       }

This following notations are used through out this document  

Notation	Description
<SAMPLE_HOME>	Folder where the OCIdriverTAFSample will be unzipped. For example, C:\OTNSamples
<JAVA_HOME>	Folder where JAVA is installed. For example, C:\jdk1.2
<ORACLE_HOME>	Folder where Oracle Database or the Client is installed. For example, C:\ora9i
<JDBC_HOME>	Folder where the Oracle JDBC driver is installed. For example, C:\ora9i\jdbc\lib

• Oracle9i JDeveloper ( Note: Oracle9i JDeveloper is Oracle's Visual Java Development Tool and can be downloaded from here )
  or JDK1.2.x or above This can be downloaded from here .
• Oracle9i Database or higher running SQL*Net TCP/IP listener. This can be downloaded from here .
  
• Oracle9i JDBC Driver. The JDBC driver is available at <ORACLE_HOME>/jdbc/lib or <OC4J_HOME>/jdbc/lib.

• Unjar the provided OCIdriverTAFSample.jar using the following command 

> jar xvf OCIdriverTAFSample.jar

Note: You will find jar.exe in <JAVA_HOME>\bin. Ensure <JAVA_HOME>\bin is present in your system path.  For setting up environment variables in different platforms, please refer environment set up readme document

This creates a folder OCIdriverTAFSample with all the source files.

• Edit Connection.properties file in <SAMPLE_HOME>\OCIdriverTAFSample directory
  Change the tnsEntry name to that of the database instance you want to connect to.

  Note: Before you run this sample, set up the following service in tnsnames.ora. It is placed in <ORACLE_HOME>\network\admin.

   tnsentryname=(DESCRIPTION= 
      (ADDRESS=(PROTOCOL=tcp)(Host=hostname)(Port=1521)) 
      (CONNECT_DATA=(SID=ORCL) 
        (FAILOVER_MODE=(TYPE=SELECT)(METHOD=BASIC))     
      ) 
   )

Database Setup

This sample application requires that the following table to exists in the OE schema.

Table Name: ORDER_DATA

Column Name                  Column Type

QUERYTIME                     DATE
NO_OF_ORDERS           NUMBER(8)

To create this table, run SQL*Plus , connect to your test database and execute the OCIdriverTAFSample.sql script as shown below.

  

SQL>@<SAMPLE_HOME>\OCIdriverTAFSample\database\OCIdriverTAFSample.sql

 

Running the application using Oracle9i JDeveloper

Back To Top

This section describes the steps required to run this application using Oracle9i JDeveloper .

• Open Oracle9i JDeveloper and use File/Open option to select the OCIdriverTAFSample.jws from the OCIdriverTAFSample directory.
• Set CLASSPATH to Oracle9i JDBC drivers. It can be done as follows:
  • Select OCIdriverTAFSample.jpr and click Project/Project Settings, it will display the Project Settings window.
  • The options will be displayed in a tree format. Under Configurations, view the currently active configuration. Go to the Libraries option under the currently active configuration.
  • To add JDBC class libraries, click New button. It will display a window New Library
  • Give some name(Oracle JDBC jars) in the Library Name field shown.
  • Click the Edit button at Class Path field, this will display a new window.
  • Click Add Entry. This will display directory browsing window
  • Browse for <ORACLE_HOME>/jdbc/lib/classes12.jar and <ORACLE_HOME>/jdbc/lib/nls_charset12.jar file.
  • Click Select button
  • Click OK till you return to the Libraries option.
    
    Note: If JDK 1.4 is used, then ojdbc14.jar (<ORACLE_HOME>/jdbc/lib) must be used instead of classes12.jar
• Next, select Project/Make OCIdriverTAFSample.jpr from main menu.
• Select the OCIdriverTAFSample.java file and select Run/Run OCIdriverTAFSample.java from JDeveloper main menu to run the application.