Error Handling and Optimizations

This section has two focuses: 1) the functionality of XA exceptions and error handling; and 2) Oracle optimizations in its XA implementation. The following topics are covered:

• XA Exception Classes and Methods

• Mapping between Oracle Errors and XA Errors

• XA Error Handling

• Oracle XA Optimizations

The exception and error-handling discussion includes the standard XA exception class and the Oracle-specific XA exception class, as well as particular XA error codes and error-handling techniques.

XA Exception Classes and Methods

XA methods throw XA exceptions, as opposed to general exceptions or SQL exceptions. An XA exception is an instance of the standard class javax.transaction.xa.XAException or a subclass. Oracle subclasses XAException with the oracle.jdbc.xa.OracleXAException class.

An OracleXAException instance consists of an Oracle error portion and an XA error portion and is constructed as follows by the Oracle JDBC driver:

public OracleXAException()

or:

public OracleXAException(int error)

The error value is an error code that combines an Oracle SQL error value and an XA error value. (The JDBC driver determines exactly how to combine the Oracle and XA error values.)

The OracleXAException class has the following methods:

• public int getOracleError()

  This method returns the Oracle SQL error code pertaining to the exception--a standard ORA error number (or 0 if there is no Oracle SQL error).

• public int getXAError()

  This method returns the XA error code pertaining to the exception. XA error values are defined in the javax.transaction.xa.XAException class; refer to its Javadoc at the Sun Microsystems Web site for more information.

Mapping between Oracle Errors and XA Errors

As of release 8.1.6 of Oracle8i, Oracle errors correspond to XA errors in OracleXAException instances as documented in Table 16-1.

Table 16-1 Oracle-XA Error Mapping

Oracle Error Code	XA Error Code
ORA 3113	XAException.XAER_RMFAIL
ORA 3114	XAException.XAER_RMFAIL
ORA 24756	XAException.XAER_NOTA
ORA 24764	XAException.XA_HEURCOM
ORA 24765	XAException.XA_HEURRB
ORA 24766	XAException.XA_HEURMIX
ORA 24767	XAException.XA_RDONLY
ORA 25351	XAException.XA_RETRY
all other ORA errors	XAException.XA_RMERR

XA Error Handling

The following example uses the OracleXAException class to process an XA exception:

try {
   ...
   ...Perform XA operations...
   ...
} catch(OracleXAException oxae) { 
  int oraerr = oxae.getOracleError();
  System.out.println("Error " + oraerr);
} 
  catch(XAException xae)
{...Process generic XA exception...}

In case the XA operations did not throw an Oracle-specific XA exception, the code drops through to process a generic XA exception.

Oracle XA Optimizations

Oracle JDBC has functionality to improve performance if two or more branches of a distributed transaction use the same database instance--meaning that the XA resource instances associated with these branches are associated with the same resource manager.

In such a circumstance, the prepare() method of only one of these XA resource instances will return XA_OK (or failure); the rest will return XA_RDONLY, even if updates are made. This allows the transaction manager to implicitly join all the transaction branches and commit (or roll back, if failure) the joined transaction through the XA resource instance that returned XA_OK (or failure).

The transaction manager can use the OracleXAResource class isSameRM() method to determine if two XA resource instances are using the same resource manager. This way it can interpret the meaning of XA_RDONLY return values.

---