4 Data Sources

Types of Data Sources

In OC4J, Data Sources are classified as follows:

• Emulated Data Sources

• Nonemulated Data Sources

• Native Data Sources

Table 4-1 summarizes the key differences between the data source types.

Figure 4-1 summarizes the decision tree that should guide you when choosing a data source type.

Figure 4-1 Choosing a Data Source Type

Description of the illustration dsdec.gif

The following sections describe each data source type in detail.

<data-source
    class="com.evermind.sql.DriverManagerDataSource"
    name=ÓOracleDSÓ
    location="jdbc/OracleCoreDS"
    xa-location="OracleDS"
    ejb-location="jdbc/OracleDS"
    connection-driver="oracle.jdbc.driver.OracleDriver"
    username="scott"
    password="tiger"
    url="jdbc:oracle:thin:@//localhost:5521/oracle.regress.rdbms.dev.us.oracle.com"
    inactivity-timeout=Ó30Ó
/>

Context ic = new InitialContext();
DataSource ds = (DataSource) ic.lookup("jdbc/OracleDS");
// This lookup could also be done as
// DataSource ds = (DataSource) ic.lookup("java:comp/env/jdbc/OracleDS");
Connection con = ds.getConnection();

Context ic = new InitialContext();
DataSource ds = (DataSource) ic.lookup("jdbc/OracleCMTDS1");
Connection conn1 = ds.getConnection("scott", "tiger");
Connection conn2 = ds.getConnection("scott", "tiger");

<data-source
  class="com.evermind.sql.OrionCMTDataSource"
  location="jdbc/OracleDS"
  connection-driver="oracle.jdbc.driver.OracleDriver"
  username="scott"
  password="tiger"
  url="jdbc:oracle:thin:@//localhost:5521/oracle.regress.rdbms.dev.us.oracle.com"
</data-source>

<data-source
    class="com.my.DataSourceImplementationClass"
    name=ÓNativeDSÓ
    location="jdbc/NativeDS"
    username="user"
    password="pswd"
    url="jdbc:myDataSourceURL"
</data-source>

Mixing Data Sources

A single application can use several different types of data sources.

If your application mixes data sources, note the following issues:

• Only emulated and nonemulated data sources support JTA transactions.

  You cannot enlist connections obtained from native data sources in a JTA transaction.

• Only nonemulated data sources support true two-phase commit (emulated data sources emulate two-phase commit).

  To enlist multiple connections in a two-phase commit transaction, all connections must use nonemulated data sources. For information on the limitations of two-phase commit, see Chapter 7, "Java Transaction API".

• If you have opened a JTA transaction and want to obtain a connection that does not participate in the transaction, then use a native data source to obtain the connection.

• If your application does not use JTA transactions, you can obtain connections from any data source.

• If your application has opened a javax.transaction.UserTransaction, all future transaction work must be performed through that object.

  If you try to invoke the connection's rollback() or commit() methods, then you will receive the following SQLException:

  calling commit() [or rollback()] is not allowed on a container-managed transactions Connection 
  
  

  The following example explains what happens:

Context ic = new InitialContext();
DataSource ds = (DataSource) ic.lookup("JDBC/OracleCMTDS1"); // Using JTA DataSources
Connection conn1 = ds.getConnection("scott", "tiger");
javax.transaction.UserTransaction ut =     (javax.transaction.UserTransaction)ic.lookup("java:comp/UserTransaction");
ut.begin();
conn1.query();
conn1.commit(); // not allowed, returns error: calling commit[or rollback] is not allowed 
                // on a container-managed transaction connection

Configuration Files

One main configuration file establishes data sources at the OC4J server level: J2EE_HOME/config/data-sources.xml.

Each application also has a separate JNDI name space. The files web.xml, ejb-jar.xml, orion-ejb-jar.xml, and orion-web.xml contain entries that you can use to map application JNDI names to data sources, as the next section describes.

<data-sources path="data-sources.xml"/>

Data Source Attributes

A data source can take many attributes. Some are required; most are optional. The required attributes are marked below. The attributes are specified in a <data-source> tag.

Table 4-4 lists and describes the data source attributes.

In addition to the data-source attributes described in Table 4-4, you can also add property subnodes to a data-source. These are used to configure generic properties on a data source object (following Java Bean conventions.) A property node has a name and value attribute used to specify the name and value of a data source bean property.

All OC4J data source attributes are applicable to the infrastructure database as well. For more information on the infrastructure database, see Oracle High Availability Architecture and Best Practices.

The following example shows the use of the clean-available-connections-threshold and rac-enabled attributes:

<data-source
    class="com.evermind.sql.OrionCMTDataSource"
    name="NEDS1"
    location="jdbc/NELoc1"
    connection-driver="oracle.jdbc.driver.OracleDriver"
    min-connections="5"
    max-connections="10"
    clean-available-connections-threshold="35"
    rac-enabled="true"
    username="scott"
    password="tiger"
    url="jdbc:oracle:thin:@//localhost:5521/oracle.regress.rdbms.dev.us.oracle.com"
    inactivity-timeout="30"
    max-connect-attempts="5"
/>

For each data source you define, OC4J may create and bind within JNDI up to four data sources: one each for location, ejb-location, xa-location, and pool-location. The type of data source selected is determined by the values associated with data-sources.xml attributes class, connection-driver, and url, and the JNDI context in which the data source object is created and looked up. For more information about data source types, see "Types of Data Sources".

Defining Data Sources in Oracle Enterprise Manager 10g

You can define any type of data source with the Oracle Enterprise Manager 10g.

The Data Sources Primer chapter of the Oracle Application Server Containers for J2EE User's Guide describes how to define data sources.

See the Oracle Application Server Containers for J2EE User's Guide to find out how to use the Administrative tools. See the Oracle Enterprise Manager Administrator's Guide for information on Oracle Enterprise Manager 10g.

This section presents a brief overview of these procedures.

Use the Oracle Enterprise Manager 10g and drill down to the Data Source page. OC4J parses the data-sources.xml file when it starts, instantiates data source objects, and binds them into the server JNDI name space. When you add a new data source specification, you must restart the OC4J server to make the new data source available for lookup.

To define emulated data sources, follow the same steps as for defining nonemulated data sources, up to the step in which you define the JNDI location. In the procedure for defining nonemulated data sources, the screen shot shows one field, Location, to be filled out. For defining an emulated data source, fill out the three fields Location, XA-Location, and EJB-Location.

Defining Data Sources in the XML Configuration File

The $J2EE_HOME/config/data-sources.xml file is preinstalled with a default data source. For most uses, this default is all you need. However, you can also add your own customized data source definitions.

The default data source is an emulated data source.

For more information about data source types, see "Types of Data Sources".

The following is a simple emulated data source definition that you can modify for most applications:

<data-source
  class="com.evermind.sql.DriverManagerDataSource"
  name="OracleDS"
  location="jdbc/OracleCoreDS"
  xa-location="OracleDS"  
  ejb-location="jdbc/OracleDS"
  connection-driver="oracle.jdbc.driver.OracleDriver"
  username="scott"
  password="tiger"
  url="jdbc:oracle:thin:@//localhost:5521/oracle.regress.rdbms.dev.us.oracle.com"
  inactivity-timeout="30"
/>

See "Data Source Attributes" for details on all data source attributes.

<data-source 
class="com.evermind.sql.DriverManagerDataSource" 
name="ds" 
location="jdbc/ds" 
xa-location="jdbc/xa/ds" 
ejb-location="jdbc/ejb/ds" 
@ connection-driver="oracle.jdbc.driver.OracleDriver" 
username="scott" 
@ password="tiger" 

@ url="jdbc:oracle:thin:@//localhost:1521/oracle.regress.rdbms.dev.us.oracle.com">
 
         <fatal-error-codes> 
            <error-code code='10'/> 
            <error-code code='20'/> 
            <error-code code='30'/> 
         </fatal-error-codes> 

</data-source> 

Password Indirection

The data-sources.xml file requires passwords for authentication. Embedding these passwords into deployment and configuration files poses a security risk, especially if the permissions on this file allow it to be read by any user. To avoid this problem, OC4J supports password indirection.

An indirect password is made up of a special indirection symbol (->) and a user name (or user name and realm). When OC4J encounters an indirect password, it uses its privileged access to retrieve the password associated with the specified user from the security store provided by a user manager.

For more information on creating users and passwords, and working with a user manager, see the section on password management in the Oracle Application Server Containers for J2EE Security Guide.

For example, the sample code under "Emulated Data Sources" contains the following line:

password="tiger"

You could replace that with the indirection symbol (->) and a user name (scott) as follows:

password="->scott"

This assumes that a user named scott with the password tiger has been created in a user manager.

Because OC4J has privileged access to the security store, it can retrieve the password (tiger) associated with this user (scott).

There are two ways to configure password indirection:

• Configuring an Indirect Password with Oracle Enterprise Manager 10g

• Configuring an Indirect Password Manually

Associating a Database Schema with a Data Source

The data source identifies a database instance. The data source schema attribute allows you to associate a data source with a database-schema.xml file that you can customize for its particular database.

When using container-managed persistence (CMP), the container is responsible for creating the database schema necessary to persist a bean. Associating a data source with a database-schema.xml file allows you to influence what SQL is ultimately generated by the container. This can help you solve problems such as accommodating additional data types supported in your application (such as java.math.BigDecimal) but not in your database.

<database-schema case-sensitive="true" max-table-name-length="30" name="MyDatabase" not-null="not null" null="null" primary-key="primary key">
    <type-mapping type="java.math.BigDecimal" name="number(20,8)" />
    <disallowed-field name="order" />
</database-schema>

Portable Data Source Lookup

When the OC4J server starts, the data sources in the data-sources.xml file in the j2ee/home/config directory are added to the OC4J JNDI tree. When you look up a data source using JNDI, specify the JNDI lookup as follows:

DataSource ds = ic.lookup("jdbc/OracleCMTDS1");

The OC4J server looks in its own internal JNDI tree for this data source.

However, we recommend—and it is much more portable—for an application to look up a data source in the application JNDI tree, using the portable java:comp/env mechanism. Place an entry pointing to the data source in the application web.xml or ejb-jar.xml files, using the <resource-ref> tag. For example:

<resource-ref>
     <res-ref-name>jdbc/OracleDS</res-ref-name>
     <res-type>javax.sql.DataSource</res-type>
     <res-auth>Container</res-auth>
</resource-ref>

where <res-ref-name> can be one of the following:

• The actual JNDI name—such as jdbc/OracleDS—that is defined in the data-sources.xml file. In this situation, no mapping is necessary. The preceding code example demonstrates this. The <res-ref-name> is the same as the JNDI name bound in the data-sources.xml file.

  Retrieve this data source without using java:comp/env, as shown by the following JNDI lookup:

  InitialContext ic = new InitialContext();
  DataSource ds = ic.lookup("jdbc/OracleDS");
  
  

• A logical name that is mapped to the actual JNDI name in the OC4J-specific files, orion-web.xml or orion-ejb-jar.xml. The OC4J-specific XML files then define a mapping from the logical name in the web.xml or ejb-jar.xml file to the actual JNDI name that is defined in the data-sources.xml file.

<resource-ref>
     <res-ref-name>jdbc/OracleMappedDS</res-ref-name>
     <res-type>javax.sql.DataSource</res-type>
     <res-auth>Container</res-auth>
</resource-ref>

<resource-ref-mapping name="jdbc/OracleMappedDS" location="jdbc/OracleDS" />

InitialContext ic = new InitialContext();
DataSource ds = ic.lookup("jdbc/OracleMappedDS");

Retrieving a Connection from a Data Source

One way to modify data in your database is to retrieve a JDBC connection and use JDBC statements. We recommend that you, instead, use data source objects in your JDBC operations.

Perform the following steps to modify data within your database:

1. Retrieve the DataSource object through a JNDI lookup on the data source definition in the data-sources.xml file.

   The lookup is performed on the logical name of the default data source, which is an emulated data source defined in the ejb-location tag in the data-sources.xml file.

   You must always cast or narrow the object that JNDI returns to the DataSource, because the JNDI lookup() method returns a Java object.

2. Create a connection to the database represented by the DataSource object.

After you have the connection, you can construct and execute JDBC statements against this database that is specified by the data source.

The following code represents the preceding steps:

Context ic = new InitialContext();
DataSource ds = (DataSource) ic.lookup("jdbc/OracleDS");
Connection conn = ds.getConnection();

Use the following methods of the DataSource object in your application code to retrieve a connection to your database:

• getConnection();

  The user name and password are those that are defined in the data source definition.

• getConnection(String username, String password);

  This user name and password overrides the user name and password that are defined in the data source definition.

If the data source refers to an Oracle database, then you can cast the connection object that is returned on the getConnection method to oracle.jdbc.OracleConnection, and use all the Oracle extensions. See "Using Oracle JDBC Extensions" for details.

The following example illustrates this:

oracle.jdbc.OracleConnection conn = 
  (oracle.jdbc.OracleConnection) ds.getConnection();

After you retrieve a connection, you can execute SQL statements against the database through JDBC.

Refer to "Retrieving Connections with a Nonemulated Data Source" for information on handling common connection retrieval error conditions.

Retrieving Connections with a Nonemulated Data Source

The physical behavior of a nonemulated data source object changes, depending on whether you retrieve a connection from the data source outside of or within a global transaction. The following sections discuss these differences:

• Retrieving a Connection Outside a Global Transaction

• Retrieving a Connection Within a Global Transaction

Context ic = new InitialContext();
DataSource ds = (DataSource) ic.lookup("jdbc/OracleCMTDS1");
txn.begin(); //start txn
Connection conn1 = ds.getConnection("scott", "tiger");
Connection conn2 = ds.getConnection("scott", "tiger");

Context ic = new InitialContext();
DataSource ds1 = (DataSource) ic.lookup("jdbc/OracleCMTDS1");
DataSource ds2 = (DataSource) ic.lookup("jdbc/OracleCMTDS2");
txn.begin; //start txn
Connection conn1 = ds1.getConnection();
Connection conn2 = ds2.getConnection();

Connection Retrieval Error Conditions

The following mistakes can create an error condition:

• Using Different User Names for Two Connections to a Single Data Source

• Improperly configured OCI JDBC Driver

Context ic = new InitialContext();
DataSource ds = (DataSource) ic.lookup("jdbc/OracleCMTDS1");
txn.begin(); //start txn
Connection conn1 = ds.getConnection("scott", "tiger"); //uses scott/tiger 
Connection conn2 = ds.getConnection("adams", "woods"); //uses scott/tiger also

Notes on Oracle JDBC-OCI driver upgrade in the Oracle Application Server

It is not possible to upgrade to an arbitrary Oracle JDBC-OCI driver version due to client library compatibility constraints. Upgrading to OCI driver versions with matching Oracle Client libraries that are installed within the Oracle Application Server 10g (10.1.2) is supported. For example, Oracle JDBC 10.1.x drivers are supported, but the Oracle JDBC 9.2.x drivers are not.

Where the use of JDBC-OCI within the Oracle Application Server is supported, it is also necessary for the opmn.xml entry for each OC4J instance to propagate appropriate ORACLE_HOME and library path values to its startup environment.

The environment variable ORACLE_HOME is common to all platforms, but the name of the environment variable that specifies the library path is different depending on the operating systems:

• LD_LIBRARY_PATH for Solaris

• SLIB_PATH for AIX

• SHLIB_PATH for HP-UX

• PATH for Windows

The generic syntax for specifying the library paths in opmn.xml looks like this:

<prop name="<LIB_PATH_VARIABLE>" value="<LIB_PATH_VARIABLE_VALUE>"/>

where <LIB_PATH_VARIABLE> should be replaced with the appropriate platform-specific variable name that specifies the library path, and

<LIB_PATH_VARIABLE_VALUE>

should be replaced with that variable's value.

Here is an example, assuming the Solaris OS:

    <process-type id="OC4J_SECURITY" module-id="OC4J">
      <environment>
        <variable id="ORACLE_HOME"
  value="/u01/app/oracle/product/inf10120"/>
        <variable
          id="LD_LIBRARY_PATH"
          value="/u01/app/oracle/product/inf10120/lib"
        />
      </environment>
      ...
   

Installing and Setting Up DataDirect JDBC Drivers

Install the DataDirect JDBC drivers as described in the DataDirect Connect for JDBC User's Guide and Reference

After you have installed the drivers, follow these instructions to set them up.

1. Unzip the content of the DataDirect JDBC drivers to the directory DDJD_INSTALL.

2. Create the directory OC4J_INSTALL/j2ee/INSTANCE_NAME/applib if it does not already exist.

3. Copy the DataDirect JDBC drivers in DDJD_INSTALL/lib to the OC4J_INSTALL/j2ee/INSTANCE_NAME/applib directory.

4. Verify that the file application.xml contains a library entry that references the j2ee/home/applib location, as follows:

   <library path="../../INSTANCE_NAME/applib" />
   
   

5. Add data sources to the file data-source.xml as described in "Example DataDirect Data Source Entries".

Example DataDirect Data Source Entries

This section shows an example data source entry for each of the following non-Oracle databases:

• SQLServer

• DB2

• Sybase

You can also use vendor-specific data sources in the class attribute directly. That is, it is not necessary to use an OC4J-specific data source in the class attribute.

For more detailed information, refer to the DataDirect Connect for JDBC User's Guide and Reference.

<data-source 
   class="com.evermind.sql.DriverManagerDataSource"
   name="MerantDS" 
   location="jdbc/MerantCoreSSDS" 
   xa-location="jdbc/xa/MerantSSXADS" 
   ejb-location="jdbc/MerantSSDS" 
   connection-driver="com.oracle.ias.jdbc.sqlserver.SQLServerDriver"
   username="test" 
   password="secret" 
   url="jdbc:oracle:sqlserver://hostname:port;User=test;Password=secret"
   inactivity-timeout="30" 
 />

<data-source 
  class="com.evermind.sql.DriverManagerDataSource"
  name="MerantDS" 
  location="jdbc/MerantDB2DS" 
  xa-location="jdbc/xa/MerantDB2XADS" 
  ejb-location="jdbc/MerantDB2DS" 
  connection-driver="com.oracle.ias.jdbc.db2.DB2Driver"
  username="test" 
  password="secret" 
  url="jdbc:oracle:db2://hostname:port;LocationName=jdbc;CollectionId=default;"
  inactivity-timeout="30" 
/>

<data-source 
  class="com.evermind.sql.DriverManagerDataSource"
  name="MerantDS" 
  location="jdbc/MerantCoreSybaseDS" 
  xa-location="jdbc/xa/MerantSybaseXADS" 
  ejb-location="jdbc/MerantSybaseDS" 
  connection-driver="com.oracle.ias.jdbc.sybase.SybaseDriver"
  username="test" 
  password="secret" 
  url="jdbc:oracle:sybase://hostname:port;User=test;Password=secret"
  inactivity-timeout="30" 
/>

Oracle Maximum Availability Architecture (MAA)

The Oracle Maximum Availability Architecture (MAA) provides recommendations and configuration instructions to help you choose and implement an Oracle platform availability architecture that best fits your availability requirements.

The main MAA recommendations are:

• Use redundant middle-tier or application tier (Oracle Application Server), network, and storage infrastructure.

• Use Oracle Data Guard to protect from human errors and data failures, and to recover from site failures.

• Use Real Application Clusters (RAC) at each site to protect from host and instance failures.

• Use sound operational best practices (such as fast-start check pointing to control the amount of time required to recover from an instance failure).

For more information about MAA, see

http://www.oracle.com/technology/deploy/availability/htdocs/maa.htm 

High Availability (HA) Support in OC4J

You can integrate OC4J with RAC, Data Guard, and TAF as part of your HA architecture.

The following sections describe configuration issues specific to OC4J that relate directly to HA. Use this information in conjunction with MAA recommendations and procedures.

The following sections discuss OC4J HA configuration issues:

• Configuring Network Failover with OC4J

• Configuring Transparent Application Failover (TAF) with OC4J

• Connection Pooling

• Acknowledging TAF Exceptions

• SQL Exception Handling

Configuring Network Failover with OC4J

To configure OC4J to use network failover:

1. Configure a network failover-enabled data source in data-sources.xml.

   For example:

   <data-source
       class="com.evermind.sql.DriverManagerDataSource"
       name="OracleDS"
       location="jdbc/OracleCoreDS"
       xa-location="jdbc/xa/OracleXADS"
       ejb-location="jdbc/OracleDS"
       connection-driver="oracle.jdbc.driver.OracleDriver"
       username="scott"
       password="tiger"
       url="jdbc:oracle:thin:@(DESCRIPTION=
           (LOAD_BALANCE=on)
           (ADDRESS=(PROTOCOL=TCP) (HOST=host1) (PORT=1521))
           (ADDRESS=(PROTOCOL=TCP) (HOST=host2) (PORT=1521))
           (CONNECT_DATA=(SERVICE_NAME=service_name)))"
       inactivity-timeout="300"
       connection-retry-interval="2"
       max-connect-attempts="60"
       max-connections="60"
       min-connections="12"
   />
   
   

   In this example, note the url element. As long as two or more hosts are specified, the JDBC client randomly chooses one of the alternatives if the current host is unreachable.

   For details on data source configuration, see "Defining Data Sources".

Configuring Transparent Application Failover (TAF) with OC4J

To configure OC4J for use with TAF:

1. Configure a TAF descriptor as described in "Configuring a TAF Descriptor (tnsnames.ora)".

2. Configure a TAF-enabled data source in data-sources.xml. For example:

   <data-source
       class="com.evermind.sql.DriverManagerDataSource"
       name="OracleDS"
       location="jdbc/OracleCoreDS"
       xa-location="jdbc/xa/OracleXADS"
       ejb-location="jdbc/OracleDS"
       connection-driver="oracle.jdbc.driver.OracleDriver"
       username="scott"
       password="tiger"
       url="jdbc:oracle:oci8:@(description=(load_balance=on)(failover=on)
         (address=(protocol=tcp)(host=db-node1)(port=1521))
         (address=(protocol=tcp)(host=db-node2)(port=1521))
         (address=(protocol=tcp)(host=db-node3)(port=1521))
         (address=(protocol=tcp)(host=db-node4)(port=1521))
         (connect_data=
           (service_name=db.us.oracle.com)
           (failover_mode=(type=select)(method=basic)(retries=20)(delay=15))))"
       rac-enabled="true"
       inactivity-timeout="300"
       connection-retry-interval="2"
       max-connect-attempts="60"
       max-connections="60"
       min-connections="12"
   />
   
   

   In this example, note that the url element failover is on and failover_mode is defined. As long as two or more hosts are specified, the JDBC client randomly chooses one of the alternatives if the current host is unreachable. For a description of failover_mode options, see Table 4-7, "TAF Configuration Options".

   For details on data source configuration, see "Defining Data Sources".

3. Configure Oracle JMS as the Resource Provider for JMS in the orion-application.xml file. For example:

   <resource-provider 
       class="oracle.jms.OjmsContext" name="cartojms1">
       <description> OJMS/AQ </description>
       <property name="datasource" value="jdbc/CartEmulatedDS"></property>
   </resource-provider>
   
   

Configuring a TAF Descriptor (tnsnames.ora)

TAF is configured using Net8 parameters in the tnsnames.ora file.

TAF can be configured by including a FAILOVER_MODE parameter under the CONNECT_DATA section of a connect descriptor. TAF supports the subparameters described in Table 4-7.

In the following example, Oracle Net connects randomly to one of the protocol addresses on sales1-server or sales2-server. If the instance fails after the connection, then the TAF application fails over to the listener on another node.

sales.us.acme.com=
    (DESCRIPTION=
        (LOAD_BALANCE=on)
        (FAILOVER=on)
        (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521))
        (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521))
        (CONNECT_DATA=
            (SERVICE_NAME=sales.us.acme.com)
            (FAILOVER_MODE=
                (TYPE=session)
                (METHOD=basic)
                (RETRIES=20)
                (DELAY=15))))

For more information on configuring TAF, refer to the "Oracle9i Net Services Administrator's Guide".

Connection Pooling

If you have a transaction spanning two beans and each bean gets a JDBC connection to the same database but different instances, then on commit, OC4J issues a simple commit (instead of a Two-Phase Commit), which makes the transaction suspect. If your application encounters such transactions, use either TAF or connection pooling, but not both.

In case of an instance failure, dead connections are cleaned from both the OC4J connection pool and from the JDBC type 2 connection pool.

If a database goes down and getConnection() is called, and if connection pooling is used, then the pool is cleaned up. The caller must catch the exception on the getConnection() call, and retry. In some cases, the OC4J container does the retries.

OC4J cleans up a connection pool when the connection is detected to be bad. That is, if getConnection() throws a SQLException with error code 3113 or 3114.

When an exception occurs while using a user connection handle, it is useful for OC4J to detect whether the exception is due to a database connection error or to a database operational error. The most common error codes thrown by the database when a connection error occurs are 3113 and 3114. These errors are returned typically for in-flight connections that get dropped. In addition, new connection attempts may receive error codes 1033, 1034, 1089 and 1090.

Fast-connection cleanup is implemented in both non-RAC and RAC environments.

In a non-RAC environment, when ajava.sql.SQLException is thrown, all unallocated connections are removed from the pool.

In a RAC environment, when ajava.sql.SQLException is thrown, first the states of all unallocated connections are checked. Connections that are alive are left alone. Otherwise, they are removed from the pool.

Acknowledging TAF Exceptions

Active Update transactions are rolled back at the time of failure because TAF cannot preserve active transactions after failover. TAF requires an acknowledgement from the application that a failure has occurred through a rollback command. In other words, the application receives an error message until a ROLLBACK is submitted.

A common failure scenario is as follows:

1. A JDBC Connection fails or is switched over by TAF.

2. TAF issues an exception.

3. TAF waits for an acknowledgement from the application in the form of a ROLLBACK.

4. The application rolls back the transaction and replays it.

Using Oracle Call Interface (OCI) callbacks and failover events, your application can customize TAF operations to automatically provide the required acknowledgement.

Your application (J2EE components) can capture the failure status of an Oracle instance and customize TAF by providing a function that the OCI library will automatically call during failover, using OCI callback capabilities. Table 4-8 describes the failover events defined in the OCI API.

For more information, see the Oracle Call Interface Programmer's Guide.

SQL Exception Handling

Depending on the driver type used, SQL Exceptions will have different error codes and transaction replay may or may not be supported.

These error codes are obtained by making a getErrorCode() call on the java.sql.SQLException thrown to the caller.

Table 4-9 summarizes these issues by driver type.