Using Third-Party JDBC XA Drivers with WebLogic Server


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| Download Documentation \| Contact \| Glossary

\| WebLogic Server Doc Home \| Programming WebLogic JTA \| Previous Topic \| Next Topic \| Contents \| Index \| View as PDF

The following sections describe how to use JDBC XA drivers in WebLogic Server transactions:

Overview of Third-Party XA Drivers

This section provides an overview to using third-party JDBC two-tier drivers with WebLogic Server in distributed transactions. These drivers provide connectivity between WebLogic Server 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 6.1:

Table 7-1 Two-Tier JDBC/XA Drivers

Driver/Database Version	Comments
Type 2 XA Drivers (native .dll)
IBM DB2 Version 7.2 Platform: NT	See Using DB2 7.2/XA Driver.
Type 4 XA Drivers (all-Java)
Oracle Thin Driver XA Driver version 8.1.7 Database version 8.1.7	See Using Oracle Thin 8.1.7/XA Driver.
Sybase jConnect/XA Version 5.2.1 Adaptive Server Enterprise 12.0	See Using Sybase jConnect 5.2.1/XA Driver.
Cloudscape Version 3.5.1	See Software Requirements for the Cloudscape 3.5.1/XA Driver.

Third-Party Driver Configuration and Performance Requirements

Here are requirements and guidelines for using specific third-party X/A drivers with with WebLogic Server.

Note: You may need to set additional connection pool properties when using third-party drivers not listed here. See Additional XA Connection Pool Properties in the Administration Guide.

Using Oracle Thin 8.1.7/XA Driver

The following sections provide information for using the Type 4 Oracle Thin 8.1.7/XA Driver with WebLogic Server 6.1.

Software Requirements for the Oracle Thin 8.1.7/XA Driver

The Oracle Thin 8.1.7/XA Driver requires the following:

JDK 1.2.x
Oracle 8.1.7 server in order to have XA functionality (limitation does not apply for non-XA usage)

Known Oracle Thin 8.1.7/XA Issues

These are the known issues and BEA workarounds::

Table 7-2 Oracle Thin Driver Known Issues and Workarounds

Description	Oracle Bug	Comments/Workarounds for WebLogic Server 6.1
ORA-01002 - Fetch out of sequence exception. Iterating result set after XAResource.end(TMSUSPEND) and XAResource.start(TMRESUME) results in ORA-01002	—	As a workaround, set the statement fetch size to be at least the result set size. This implies that the Oracle Thin 8.1.7 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.
XAResource.end(TMSUSPEND) followed by XAResource.end(TMSUCCESS) gives XAER_RMERR.	1527725	WebLogic Server has provided an internal workaround for this bug.
Driver hangs or gives XAER_RMERR for multi-threaded XA usage.	1569235	WebLogic Server has provided an internal workaround for this bug.
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.
XAResource.recover repeatedly returns the same set of in-doubt Xids irrespective of the input flag. According to the XA spec, the Transaction Manager should initially call XAResource.recover with TMSTARTRSCAN and then call XAResource.recover with TMNOFLAGS repeatedly until no Xids are returned. This Oracle bug could lead to infinite recursion and subsequent running out of Oracle cursors with error "ORA-01000: maximum open cursors exceeded."	—	Weblogic Server provides an internal workaround for this issue.

Set the Environment for the Oracle Thin 8.1.7/XA Driver

Set the environment as follows:

Enable the database server for XA

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 public

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 crash, recover for the Oracle resource will fail with XAER_RMERR.

Oracle Thin 8.1.7/XA Driver Configuration Properties

The following table contains sample code for configuring a Connection Pool:

Oracle Thin 8.1.7/XA Driver: Connection Pool Configuration

Property Name	Property Value
Name	jtaXAPool
Targets	myserver,server1
URL	jdbc:oracle:thin:@baybridge:1521:bay817
DriverClassname	oracle.jdbc.xa.client.OracleXADataSource
Initial Capacity	1
MaxCapacity	20
CapacityIncrement	2
Properties	user=scott;password=tiger

The following table contains sample code for configuring a TxDataSource:

Table 7-3 Oracle Thin 8.1.7/XA Driver: TxDataSource Configuration

Property Name	Property Value
Name	jtaXADS
Targets	myserver,server1
JNDIName	jtaXADS
PoolName	jtaXAPool

Using Sybase jConnect 5.2.1/XA Driver

The following sections provide important configuration information and performance issues when using the Sybase jConnect Driver 5.2.1/XA Driver.

Known Sybase jConnect 5.2.1/XA Issues

These are the known issues and BEA workarounds:

Table 7-4 Sybase jConnect 5.2.1 Known Issues and Workarounds

Description	Sybase Bug	Comments/Workarounds for WebLogic Server 6.1
When calling setAutoCommit(true)the following exception is thrown: java.sql.SQLException: JZ0S3: The inherited method setAutoCommit(true) cannot be used in this subclass.	10726192	No workaround. Vendor fix required.
When driver used in distributed transactions, calling XAResource.end(TMSUSPEND) followed by XAResource.end(TMSUCCESS) results in XAER_RMERR.	10727617	WebLogic Server has provided an internal workaround for this bug: Set the connection pool property XAEndOnlyOnce="true". Vendor fix has been requested.

Description

Sybase Bug

Comments/Workarounds for WebLogic Server 6.1

When calling setAutoCommit(true)the following exception is thrown:

java.sql.SQLException: JZ0S3: 
The inherited method setAutoCommit(true)
cannot be used in 
this subclass.

10726192

No workaround. Vendor fix required.

When driver used in distributed transactions, calling XAResource.end(TMSUSPEND) followed by XAResource.end(TMSUCCESS) results in XAER_RMERR.

10727617

WebLogic Server has provided an internal workaround for this bug:

Set the connection pool property XAEndOnlyOnce="true".

Vendor fix has been requested.

Set the Environment for the Sybase jConnect/XA Driver

Follow these instructions to setup your environment:

set CLASSPATH=.;%SYBASE_INSTALL_DIR%
\jCONNECT-5_2\classes\jconn2.jar
where SYBASE_INSTALL_DIR is the directory where you installed the Sybase driver.
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_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

Connection Pools for the Sybase jConnect 5.2.1/XA Driver

The following table contains sample code for configuring a Connection Pool:

Table 7-5 Sybase jConnect 5.2.1/XA Driver: Sample Connection Pool Configuration

Property Name	Property Value
Name	jtaXAPool
Targets	myserver,server1
DriverClassname	com.sybase.jdbc2.jdbc.SybXADataSource
Properties	User=dbuser; DatabaseName=dbname; ServerName=server_name_or_IP_address; PortNumber=serverPortNumber; NetworkProtocol=Tds; resourceManagerName=Lrm_name_in_xa_config; resourceManagerType=2
Password	dbpassword
Initial Capacity	1
MaxCapacity	10
CapacityIncrement	1

Where Lrm_name refers to the Logical Resource Manager name.

Note: You must also add KeepXAConnTillTxComplete="true" to the connection pool tag in the config.xml file. See Additional XA Connection Pool Properties in the Administration Guide.

The following table contains sample code for configuring a TxDataSource:

Table 7-6 Sybase jConnect 5.2.1/XA Driver: TxDataSource Configuration

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.

Table 7-7 Sybase jConnect 5.2.1/XA Driver: Java Client Connection Properties

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	4100

Using Cloudscape 3.5.1/XA Driver

The following sections provide information for using the Type 2 Cloudscape 3.5.1/XA Driver with WebLogic Server 6.1.

Software Requirements for the Cloudscape 3.5.1/XA Driver

The Cloudscape 3.5.1/XA Driver supports JDK 1.3 RC1. For more information, see http://www.cloudscape.com/support/techinfo.jsp.

Known Cloudscape 3.5.1/XA Driver Issues

The following table contains known issues:

Table 7-8 Cloudscape 3.5.1/XA Driver Known Issues

Description	Cloudscape Enhancement Request	Comments/Workarounds for WebLogic Server 6.1
No known issues.		.

Set the Environment for the Cloudscape 3.5.1/XA Driver

Set the following environment variables (assuming NT syntax):

set CLOUDSCAPE_INSTALL=<directory where Cloudscape is installed>
set CLASSPATH=.;%cloudscape_install%\lib\cloudscape.jar;
%cloudscape_install%\lib\cloudsync.jar;
%cloudscape_install%\lib\client.jar;%cloudscape_install%\lib\
tools.jar;c:\weblogic\dev\src\3rdparty\weblogicaux.jar

Note: Note that the weblogicaux.jar is for the javax classes only.

Cloudscape 3.5.1/XA Driver Configuration Properties

The following table contains sample code for configuring a Connection Pool:

Table 7-9 Cloudscape 3.5.1/XA Driver: Connection Pool Configuration

Property Name	Property Value
Name	jtaXAPool
Targets	myserver,server1
DriverClassname	COM.cloudscape.core.XaDataSource
Initial Capacity	1
Max Capacity	10
Capacity Increment	2
Properties	databaseName=CloudscapeDB; createDatabase=create
Supports Local Transaction	True

The following table contains sample code for configuring a TxDataSource:

Table 7-10 Cloudscape 3.5.1/XA Driver: TxDataSource Configuration

Property Name	Property Value
Name	jtaXADS
Targets	myserver,server1
JNDIName	jtaXADS
PoolName	jtaXAPool

Using DB2 7.2/XA Driver

The following sections describe how to set your environment to use the Type2 DB2 7.2/XA Driver with WebLogic Server 6.1.

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

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.

DB2 7.2/XA Driver Configuration Properties

The following table contains sample code for configuring a Connection Pool:

Table 7-11 DB2 7.2/XA Driver: Connection Pool Configuration

Property Name	Property Value
Name	jtaXAPool
Targets	server1
DriverClassname	COM.ibm.db2.jdbc.DB2XADataSource
Initial Capacity	1
MaxCapacity	10
CapacityIncrement	2
Properties	user=db2admin; password=db2admin; DatabaseName=NEWDEMO

Note: You must also add KeepXAConnTillTxComplete="true" to the connection pool tag in the config.xml file. See Additional XA Connection Pool Properties in the Administration Guide.

The following table contains sample code for configuring a TxDataSource:

Table 7-12 DB2 7.2/XA Driver: TxDataSource Configuration

Property Name	Property Value
Name	jtaXADS
Targets	server1
JNDIName	jtaXADS
PoolName	jtaXAPool

Other Third-Party XA Drivers

To use other third-party XA-compliant JDBC drivers, you must include the path to the driver class libraries in your CLASSPATH.