Using Third-Party JDBC XA Drivers with WebLogic Server

This section discusses the following topics:

• Overview of Third-Party XA Drivers

• Third-Party Driver Configuration and Performance Requirements

 

---

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:

Table 7-1 Two-Tier JDBC/XA Drivers

Driver/Database Version	Comments
Oracle Thin Driver XA Driver version 8.1.7, 9.0.1, 9.2.0, 10.1.0 Database version 8.1.7, 9.0.1, 9.2.0, 10g	See Using Oracle Thin/XA Driver.
Sybase jConnect/XA Driver version 5.5 Adaptive Server Enterprise 12.0	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 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/XA Driver

WebLogic Server ships with the Oracle Thin Driver version 10g preconfigured and ready to use. If you want to use a different version of the Oracle Thin Driver, 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:

• JDK 1.2.x or later (WebLogic Server ships with JDK 1.3.1_XX)

• The server version must match the driver version that you are using with WebLogic Server. For example, if you use the 8.1.7 version of the Oracle Thin/XA Driver, you must also install the 8.1.7 version of the Oracle server.

Known Oracle Thin 8.1.7/XA Issues

The following table lists known issues and BEA workarounds

.

Table 7-2 Oracle Thin Driver Known Issues and Workarounds

Description	Oracle Bug	Comments/Workarounds for WebLogic Server
With the 9.2.0.1 version of the driver, when creating or adding a row to a table via an Entity EJB (1.x) with timestamp used as a composite of the primary key, the bean cannot be found and a NoSuchEntityException is thrown.		This error appears when using the Oracle Thin Driver 9.2.0 installed with WebLogic Server 7.0SP2. Workaround: Use the latest version of the driver from Oracle. See "Changing or Updating the Oracle Thin Driver" in Programming WebLogic JDBC for instructions.
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: 1. pstmt.setNull(1, java.sql.Types.REAL) 2. pstmt.addBatch() 3. pstmt.setNull(1, 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

WebLogic Server ships with the Oracle Thin Driver version 10g preconfigured and ready to use. If you want to use Oracle Thin Driver version 9.x, you must replace the version of classes12.zip in WL_HOME\server\lib with the 9.x version. See Changing or Updating the Oracle Thin Driver in Programming WebLogic JDBC.

Note: The classes12.zip file is included in the WL_HOME\server\lib folder and is referenced in the weblogic.jar manifest file. When you start WebLogic Server, the driver is loaded automatically and is ready to use with WebLogic Server. To use this driver with the WebLogic utilities or with other applications, you must include the path to this file in your CLASSPATH.

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:

Oracle Thin/XA Driver: Connection Pool Configuration

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 code for configuring a TxDataSource:

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

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

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:

Table 7-4 Sybase jConnect 5.5 Known Issues and Workarounds

Description	Sybase Bug	Comments/Workarounds for WebLogic Server
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 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, you must include the path to these files in your CLASSPATH.

Connection Pools for the Sybase jConnect 5.5/XA Driver

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

Table 7-5 Sybase jConnect 5.5/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
Initial Capacity	1
MaxCapacity	10
CapacityIncrement	1
Supports Local Transaction	True

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.5/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.5/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	port (Typically 4100)

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 and follow the configuration instructions provided by the vendor.