Using Third-Party JDBC XA Drivers with WebLogic Server
This section discusses the following topics:
Overview of Third-Party XA Drivers
This section provides an overview of using third-party JDBC two-tier drivers with WebLogic Server in distributed transactions. These drivers provide connectivity between WebLogic Server connection pools and the DBMS. Drivers used in distributed transactions are designated by the driver name followed by /XA; for example, Oracle Thin/XA Driver.
Table of Third-Party XA Drivers
The following table summarizes known functionality of these third-party JDBC/XA drivers when used with WebLogic Server:
|
Driver/Database Version |
Comments |
|---|---|
| Oracle Thin Driver XA | See Using Oracle Thin/XA Driver. |
| IBM DB2 Type 2 | See Using the IBM DB2 Type 2 XA JDBC Driver. |
Sybase jConnect/XA
|
See Using Sybase jConnect 5.5/XA Driver.
|
Third-Party Driver Configuration and Performance Requirements
Here are requirements and guidelines for using specific third-party XA drivers with WebLogic Server.
Using Oracle Thin/XA Driver
WebLogic Server ships with the Oracle Thin Driver version 9.2.0 preconfigured and ready to use. If you want to update the driver or use a different version, see Changing or Updating the Oracle Thin Driver in Programming WebLogic JDBC.
The following sections provide information for using the Oracle Thin/XA Driver with WebLogic Server.
Software Requirements for the Oracle Thin/XA Driver
The Oracle Thin/XA Driver requires the following:
- Java 2 SDK 1.4.x or later. WebLogic Server requires a Java 2 SDK 1.4.X (and ships with SDK 1.4.1_XX). Note that the Oracle 9.2.0 Thin driver (ojdbc14.jar) is the only version of the driver supported for use with a Java 2 SDK 1.4.X.
- Oracle server configured for XA functionality (limitation does not apply for non-XA usage).
Known Oracle Thin Driver Issues
Table 7-2 lists known issues and workarounds for the Oracle Thin driver. See the Oracle Web site for the most up-to-date information about these issues.
|
Description |
Oracle Bug |
Comments/Workarounds for WebLogic Server |
|---|---|---|
| When using the 9.2.0.3 or earlier version of the Oracle Thin driver, after restarting WebLogic Server, you may see an XAER_PROTO error or an intermittent hang. | 2717235 | This situation occurs because on server restart, WebLogic Server calls XA.recover() to recover any pending transactions. With the 9.2.0.3 or earlier version of the Oracle Thin driver, the Oracle DBMS opens a local transaction to complete the transaction recovery work, but the local transaction is never closed. When the connection used to recover transactions is returned to the connection pool and is then reused by an application, the local transaction is still present. With the first operation on the connection, an XAER_PROTO error is thrown. (If TestConnsOnReserve is set to true, the connection test is the first operation on the connection.) WebLogic Server then attempts to unregister the connection with the resource and waits a fixed amount of time for all transaction work on the resource to complete. This may appear as a hang.Oracle has provided a patch for this bug. You can download the patch from the Oracle Metalink Web site. Refer to the Oracle bug number 2717235.This issue is fixed in version 9.2.0.4 and 10G. |
| The 9.2.0.1 and 9.2.0.2 versions of the Oracle Thin driver do not allow you to work with a BLOB in tables that also contain a long raw. When you retrieve a BLOB from the table and call blob.length(), you will get a SQL protocol violation. | 2696397 | This issue is fixed in version 9.2.0.3 and 10G. |
When using the Oracle 9.2.0.1 or 9.2.0.2 Thin driver, you will get a null pointer exception when you run addBatch with setNull with a data conversion. For example, the following will fail with the Oracle 9.2.0 Thin driver:
java.sql.Types.REAL)
java.sql.Types.VARCHAR) |
| This issue is fixed in version 9.2.0.3 and 10G. |
| The 9.2.0.1 and 9.2.0.2 versions of the Oracle Thin driver do not allow you to work with a CLOB in tables that also contain a long. When you retrieve a CLOB from the table and call clob.length(), you will get a SQL protocol violation. |
| Workaround: In this scenario, you can read the LONG column before calling clob.length().This issue is fixed in version 9.2.0.3 and 10G. |
| The 9.2.0.1 and 9.2.0.2.0 versions of the Oracle Thin driver do not allow you to use "alter session set NLS_DATE_FORMAT='YYYY-MM-DD HH24:MI:SS'" to change the default Oracle timestamp format. Previous versions did allow this. | 2632931 | TAR number 2677656.995.Fixed in 9.2.0.2.1. Oracle has provided a patch for this bug. You can download the patch from the Oracle Metalink Web site. Refer to the Oracle bug number 2632931. |
| ORA-01453 - SET TRANSACTION must be first statement of transaction |
| When using the Oracle Thin/XA driver, you cannot change the transaction isolation level for a transaction. Transactions use the default transaction isolation as set for the database. |
| ORA-01002 - Fetch out of sequence exception. Iterating result set after XAResource.end(TMSUSPEND) and XAResource.start(TMRESUME) results in ORA-01002 This also occurs when an external client gets a result set using a pooled connection in WebLogic Server that uses the Oracle Thin driver. When the result set is sent to the client, the current transaction is suspended. | - | As a workaround, set the statement fetch size to be at least the result set size. This implies that the Oracle Thin Driver cannot be used on the client side or that the bean cannot keep result sets open across method invocations, unless this workaround is used.This is an Oracle limitation that Oracle does not intend to fix. |
| Does not support update with no global transaction. If there is no global transaction when an update is attempted, Oracle will start a local transaction implicitly to perform the update, and subsequent reuse of the same XA connection for global transaction will result in XAER_RMERR. Moreover, if application attempts to commit the local transaction via either setting auto commit to true or calling Connection.commit() explicitly, Oracle XA driver returns "SQLException: Use explicit XA call." | - | Applications should always ensure that there is a valid global transaction context when using the XA driver for update. That is, ensure that bean methods have transaction attributes Required, RequiresNew, or Mandatory. |
Set the Environment for the Oracle Thin/XA Driver
Configure WebLogic Server
See "Using the Oracle Thin Driver in Programming WebLogic JDBC.
Enable XA on the Database Server
To prepare the database for XA, perform these steps:
- Log on to sqlplus as system user, e.g. sqlplus sys/CHANGE_ON_INSTALL@<DATABASE ALIAS NAME>
- Execute the sql: grant select on DBA_PENDING_TRANSACTIONS to user where user is the user account used to create database connections in a connection pool. Execute this command for each user account used in XA connection pools in your WebLogic Server domain.
If the above steps are not performed on the database server, normal XA database queries and updates may work fine. However, when the Weblogic Server Transaction Manager performs recovery on a re-boot after a crash, recover for the Oracle resource will fail with XAER_RMERR. Crash recovery is a standard operation for an XA resource.
Oracle Thin/XA Driver Configuration Properties
The following table contains sample code for configuring a Connection Pool:
|
Property Name |
Property Value |
|---|---|
| Name | jtaXAPool |
| Targets | myserver,server1 |
| URL | jdbc:oracle:thin:@serverName:port(typically 1521 on Windows):sid |
| DriverClassname | oracle.jdbc.xa.client.OracleXADataSource |
| Initial Capacity | 1 |
| MaxCapacity | 20 |
| CapacityIncrement | 2 |
| Properties | user=scott;password=tiger |
The following table contains sample attributes for configuring a TxDataSource. To create a TxDataSource from the Administration Console, select Honor Global Transactions when creating a data source.
|
Property Name |
Property Value |
|---|---|
| Name | jtaXADS |
| Targets | myserver,server1 |
| JNDIName | jtaXADS |
| PoolName | jtaXAPool |
Using the IBM DB2 Type 2 XA JDBC Driver
The following sections describe how to set your environment to use the Type2 DB2 7.2/XA Driver with WebLogic Server.
For installation instructions and connection pool configuration instructions, see "Installing and Using the IBM DB2 Type 2 JDBC Driver in Programming WebLogic JDBC at ../jdbc/thirdparty.html#db2.
Set the Environment for the DB2 7.2/XA Driver
Set your environment as follows:
- Execute the batch file usejdbc2.bat located in the <db2>/java12 directory to extract the correct version of the db2java.zip file and move it to the proper location. This enables the JDBC2.0 features of the driver. Make sure that no DB2 processes are running before executing this batch file.
- Include <db2>/java/db2java.zip in the CLASSPATH environment variable.
- Include <db2>/bin in PATH environment variable.
Where <db2> represents the directory in which the DB2 server is installed.
Limitation and Restrictions using DB2 as an XAResource
- In case of multiple connection-pooled configurations, each connection pool should have separate database instance.
- A transaction cannot be initiated with a resource that is already associated with a suspended transaction. In this case, a javax.transaction.InvalidTransactionException (attempt to resume an inactive transaction) is thrown. If in between suspend and resume, an intermediate transaction enlists the same resource as used in the suspended transaction, a javax.transaction.invalidtransation exception is thrown. If a different resource is used inside the intermediate transaction, it works fine.
Using Sybase jConnect 5.5/XA Driver
The following sections provide important configuration information and performance issues when using the Sybase jConnect Driver 5.5/XA Driver.
Known Sybase jConnect 5.5/XA Issues
These are the known issues and BEA workarounds:
Set Up the Sybase Server for XA Support
Follow these instructions to set up the environment on your database server:
- Install license for Distributed Transaction Management.
- Run sp_configure "enable DTM",1 to enable transactions.
- Run sp_configure "enable xact coordination",1.
- Run grant role dtm_tm_role to <USER_NAME>.
- Copy the sample xa_config file from the SYBASE_INSTALL\OCS-12_0\sample\xa-dtm subdirectory up three levels to SYBASE_INSTALL,where SYBASE_INSTALL is the directory of your Sybase server installation. For example:
$ SYBASE_INSTALL\xa_config
- Edit the xa_config file. In the first [xa] section, modify the sample server name to reflect the correct server name.
To prevent deadlocks when running transactions, enable row level lock by default:
- Run sp_configure "lock scheme",0,datarows
Note: Both the jConnect.jar and jconn2.jar files are included in the WL_HOME\server\lib folder and are referenced in the weblogic.jar manifest file. When you start WebLogic Server, the drivers are loaded automatically and are ready to use with WebLogic Server. To use these drivers with the WebLogic utilities or with other applications, include the path to these files in your CLASSPATH.
Notes About XA and Sybase Adaptive Server
Correct support for XA connections is available in the Sybase Adaptive Server Enterprise 12.0 and later versions only. XA connections with WebLogic Server are not supported on Sybase Adaptive Server 11.5 and 11.9.
Execution Threads and Transactions in Sybase Adaptive Server
Prior to Adaptive Server version 12.0, all resources of a transaction were privately owned by a single task on the server. The server could not share a transaction with any task other than the one that initiated the transaction. Adaptive Server version 12.x includes support for the suspend and join semantics used by XA-compliant transaction managers (such as WebLogic Server). Transactions can be shared among different execution threads, or may not be associated with an execution thread (detached).
Setting the Timeout for Detached Transactions
On the Sybase server, you can set the dtm detach timeout period, which sets the amount of time (in minutes) that a distributed transaction branch can remain in the detached state (without an associated execution thread). After this period, the DBMS automatically rolls back the transaction. The dtm detach timeout period applies to all transactions on the database server. It cannot be set for each transaction.
For example, to automatically rollback transactions after being detached for 10 minutes, use the following command:
sp_configure 'dtm detach timeout period', 10
You should set the dtm detach timeout period higher than the transaction timeout to prevent the database server from rolling back the transaction before the transaction times out in WebLogic Server. For information about setting the transaction timeout, see "JTA in the Administration Console Online Help.
For more information about the dtm detach timeout period, see the Sybase documentation.
Transaction Behavior on Sybase Adaptive Server
If a global transaction is started on the Sybase server, but is not completed, the outcome of the transaction varies depending on the transaction state before the transaction is abandoned:
- If the client is terminated before the xa.end call, the transaction is rolled back.
- If the client is terminated after the xa.end call, the transaction remains on the database server (and holds all relevant locks).
- If an application calls xa.start but has not called xa.end and the application terminates unexpectedly, the database server immediately rolls back the transaction and frees locks held by the transaction.
- If an application calls xa.start and xa.end and the application terminates unexpectedly, the database server rolls back the transaction and frees locks held by the transaction after the dtm detach timeout period has elapsed. See Setting the Timeout for Detached Transactions.
- If an application calls xa.start and xa.end, and then the transaction is prepared, if the application terminates unexpectedly, the transaction will persist so that it can be properly recovered. The Transaction Manager must call rollback or commit to complete the transaction.
Connection Pools for the Sybase jConnect 5.5/XA Driver
The following table contains sample code for configuring a Connection Pool:
Where Lrm_name refers to the Logical Resource Manager name.
The following table contains sample code for configuring a TxDataSource:
|
Property Name |
Property Value |
|---|---|
| Name | jtaXADS |
| Targets | server1 |
| JNDIName | jtaXADS |
| PoolName | jtaXAPool |
Configuration Properties for Java Client
Set the following configuration properties when running a Java client.
|
Property Name |
Property Value |
|---|---|
| ds.setPassword | <password> |
| ds.setUser | <username> |
| ds.setNetworkProtocol | Tds |
| ds.setDatabaseName | <database-name> |
| ds.setResourceManagerName | <Lrm name in xa_config file> |
| ds.setResourceManagerType | 2 |
| ds.setServerName | <machine host name> |
| ds.setPortNumber | port (Typically 4100) |
Other Third-Party XA Drivers
To use other third-party XA-compliant JDBC drivers, include the path to the driver class libraries in your CLASSPATH and follow the configuration instructions provided by the vendor.
|
|
|