Oracle8i JDBC Developer's Guide and Reference Release 3 (8.1.7) Part Number A83724-01 |
Library | Service | Contents | Index

## 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.

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index