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:
Third-Party Driver Configuration and Performance Requirements
Here are requirements and guidelines for using specific third-party XA drivers with with WebLogic Server.
Using Oracle Thin/XA Driver
WebLogic Server ships with the Oracle Thin Driver version 8.1.7 preconfigured and ready to use. If you want to use Oracle Thin Driver version 9.0.1, 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_02)
- Oracle server in order to have XA functionality (limitation does not apply for non-XA usage). 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
|
|
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/XA Driver
Configure WebLogic Server
WebLogic Server ships with the Oracle Thin Driver version 8.1.7 preconfigured and ready to use. If you want to use Oracle Thin Driver version 9.0.1, you must replace the version of classes12.zip in WL_HOME\server\lib with the 9.0.1 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 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 a crash, recover for the Oracle resource will fail with XAER_RMERR.
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_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.
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.
