Database Administration Guide

XA Support

This section describes XA support in WebLogic Portal 8.1. For additional information about using an XA configuration, see http://download.oracle.com/docs/cd/E13196_01/platform/docs81/confgwiz/index.html.

About XA

An XA (global) transaction can span multiple databases. For example, it's common for multiple application components doing database work to be invoked as part of a single transaction. Without XA, the only way for this to work is if all transaction participants use the same database connection. With XA, you can use a TxDataSource in WLS for distributed transactions so that application components can use a different database connection for each part of the transaction.

Figure 7-1 XA Transaction Diagram

XA Transaction Diagram

What Makes a Transaction Distributed?

WebLogic Server 8.1 enables distributed transactions by providing support for XA drivers. An XA driver can guarantee atomicity of updates across multiple participating resources. Two things are required: Configuration settings and application code.

XA transaction support requires two configuration steps:

Change the Connection Pool driver to use an XA Driver.
Make sure the data source for that pool is a TxDataSource instead of a DataSource.

When using an XA driver, a TxDataSource can only point to a single connection pool. Put another way, you cannot have multiple TxDataSources pointing to the same connection pool.

XA-Compliant Code

Configuration is only part of the process for making your application XA-compliant. You must also ensure that your application code is honoring the requirements for participating in an XA transaction. For WebLogic Portal, the following data sources associated with XA-compliant code:

contentDataSource
cgDataSource
portalFrameworkPool
commercePool

Note: If you are using commerce.jar (which is not a default part of a portal application), then the commercePool data source must point to a non-XA connection pool. Commerce code is not XA-compliant.

Using XA versus Non-XA Mode: Programming Applications

This section deals with Oracle specifically, but the programming principles apply to writing XA-compliant code in general. Applications participating in distributed transaction (XA) mode can use the JDBC 2.0 Core API the same way as in local transaction (non-XA) mode, with the following exceptions:

Connections have to be obtained via the JDBC 2.0 javax.sql.DataSource API, but not through the deprecated java.sql.DriverManager or java.sql.Driver API.
When used in WebLogic Server, you must access your connection pool using a TxDataSource, not a DataSource, in order to use XA.
Attempting to enable autocommit mode by calling the java.sql.Connection.setAutoCommit method on the Connection will throw an SQLException.
Attempting to complete the distributed transaction by calling java.sql.Connection.commit or java.sql.Connection.rollback methods will throw an SQLException.

Deciding When to Use TxDataSource Instead of DataSource

Contrary to what the name implies, a DataSource is transactional. It differs from a TxDataSource in that it can support local transactions only.

The following criteria indicate the use of a TxDataSource instead of a DataSource:

The EJB container is managing your transactions.
All EJBs in an application must use a TxDataSource, and each TxDataSource must point to the same connection pool.
Multiple databases are updated within a single transaction
Multiple resources, such as a database and the Java Messaging Service (JMS), are accessed during a transaction

For more information on this subject, consult the JDBC FAQ:

http://download.oracle.com/docs/cd/E13222_01/wls/docs81/faq/jdbc.html#499904

Using XA

This section explains some critical factors in providing XA support to your applications.

Combining XA and Non-XA Drivers in the Same Application

You can configure one connection pool to use an XA-compliant driver, and another to use a non-XA driver. Then simply point your DataSources to the appropriate pool. Local and global transactions may not be mixed using the same data source.

Mixing XA and Non-XA Transactions

You don't have to worry about transaction management, mixing XA and non-XA, if you use a TxDataSource, as described in the section Using TxDataSource on a Non-XA Connection Pool. The transaction manager (XA) handles suspending the existing XA transaction and starts the local transaction using the DataSource (non-XA) connection. The developer, when using a DataSource to do local transaction work, must commit and close the connection (rolling back if any exceptions occur). This is because, if an XA transaction is started afterwards, the connection will still be in a 'local' mode, and the XA driver may not accept being in local mode.

Using TxDataSource on a Non-XA Connection Pool

You can use a TxDataSource to point to 'commercePool' when it's not using an XA driver. The platform detects that no XA transaction is active, and will handle things such that there is no extra overhead (such as unrequired XA-related calls).

Configuring XA

This section includes examples of config.xml files that illustrate XA configuration by example.

Note: These are only partial config.xml files to illustrate the database configurations with XA. They are not complete config.xml files

Supporting WebLogic Content Management

The Content Management mechanism provided out of the box with WebLogic Portal 8.1 employs a special datasource to track content objects. This datasource, called p13n_sequencerDataSource, must be hosted by the same database as the content management repository.

To configure the data source, go to the WLS console --> Services --> JDBC --> Data Sources and click on 'Configure a new JDBC Data Source'. Set the name of the Data Source to "p13n_sequencerDataSource" and set the JNDI name to "p13n.sequencerDataSource". The JDBC Connection Pool must match the one used by contentDataSource. Since the p13n_sequencerDataSource does not support XA, it should point to a non-xa driver.

Examples of XA Configuration

This section includes partial config.xml files meant to show what settings are required to support XA in applications.

XA for Oracle in Portal Domain

Listing 7-1 illustrates XA support for Oracle in a Portal Domain.

Note: 'cgJMSStore' and 'cgPool' will use 'auxPool'

Listing 7-1 Configuration for XA on Oracle in a Portal Domain

<?xml version="1.0" encoding="UTF-8"?>

<Domain Name="portalDomain">

    <!-- This pool should NEVER be configured with an XA driver -->

    <JDBCConnectionPool CapacityIncrement="1"

        DriverName="oracle.jdbc.driver.OracleDriver"

        InitialCapacity="5" MaxCapacity="50" Name="auxPool"

        Properties="user=<yourUserName>;" Password="<yourPassword>"

        Targets="<yourServerName>"

URL="jdbc:oracle:thin:@<TNSNAME>:<port>:<dbHostMachineName>"/>

<!-- This pool has been configured with an XA driver.  As for all XA pools, only one TxDataSource may connect to it. In this case, it's the  'commercePool' TxDataSource -->

    <JDBCConnectionPool CapacityIncrement="1"

        DriverName="oracle.jdbc.xa.client.OracleXADataSource"

        KeepXAConnTillTxComplete="true"

        InitialCapacity="5" MaxCapacity="20" Name="portalPool"

	 Properties="user=<yourUserName>;" Password="<yourPassword>"

        Targets="<yourServerName>"

URL="jdbc:oracle:thin:@<TNSNAME>:<port>:<dbHostMachineName>"/>

<!-- This pool has been configured with an XA driver.  As for all XA pools, only one TxDataSource may connect to it. In this case, it's the  'contentDataSourcl' TxDataSource -->

    <JDBCConnectionPool CapacityIncrement="1"

        DriverName="oracle.jdbc.xa.client.OracleXADataSource"

        KeepXAConnTillTxComplete="true"

        InitialCapacity="5" MaxCapacity="15" Name="contentPool"

	 Properties="user=<yourUserName>;" Password="<yourPassword>"

	 RefreshMinutes="0" Targets="<yourServerName>"

	 URL="jdbc:oracle:thin:@<TNSNAME>:<port>:<dbHostMachineName>"/>

<!-- This pool has been configured with an XA driver.  As for all XA pools, only one TxDataSource may connect to it.  In this case, it's the  ''portalFrameworkPool" TxDataSource  -->

    <JDBCConnectionPool CapacityIncrement="1"

        DriverName="oracle.jdbc.xa.client.OracleXADataSource"

        KeepXAConnTillTxComplete="true"

        InitialCapacity="5" MaxCapacity="20" Name="portalFrameworkPool"

	 Properties="user=<yourUserName>;" Password="<yourPassword>"

        Targets="<yourServerName>"

	 URL="jdbc:oracle:thin:@<TNSNAME>:<port>:<dbHostMachineName>"/>

<!-- First, the non-XA data sources.  These must only point to 'auxPool' -->

    <JDBCDataSource

        JNDIName="p13n.trackingDataSource"

        Name="p13n_trackingDataSource" PoolName="auxPool"

	 Targets="portalServer"/>

	<JDBCDataSource JNDIName="p13n.sequencerDataSource"

        Name="p13n_sequencerDataSource" PoolName="auxPool"

	 Targets="portalServer"/>

	<JDBCDataSource JNDIName="p13n.dataSyncDataSource"

        Name="p13n_dataSyncDataSource" PoolName="auxPool"

	 Targets="portalServer"/>

<!-- Although ebusiness can't partipate in XA, it must still use a TxDataSource (because it uses EJBs), and point to the non-XA pool -->

    <JDBCTxDataSource

        JNDIName="weblogic.jdbc.jts.ebusinessPool" Name="ebusinessPool"

        PoolName="auxPool" Targets="portalServer"/>

 

<!-- Next, the XA data sources.  Each one must point to its own connection pool -->

    <JDBCTxDataSource

        JNDIName="weblogic.jdbc.jts.commercePool" Name="commercePool"

        PoolName="portalPool" Targets="portalServer"/>

    <JDBCTxDataSource

        JNDIName="contentDataSource" Name="contentDataSource"

        PoolName="contentPool" Targets="portalServer"/>

    <JDBCTxDataSource

        JNDIName="portalFrameworkPool" Name="portalFrameworkPool"

        PoolName="portalFrameworkPool" Targets="portalServer"/>

 

<!-- The JMS data stores should all point to the non-XA pool and have a null prefix -->

     <JMSJDBCStore ConnectionPool="auxPool" Name="cgJMSStore" PrefixName=""/>

</Domain>

XA for SQL Server in a Portal Domain

Note: 'cgJMSStore' and 'cgPool' will use 'auxPool'

Listing 7-2 Configuration Settings for XA on SQL Server in a Portal Domain

<?xml version="1.0" encoding="UTF-8"?>

<Domain Name="portalDomain">

    <!-- This pool should NEVER be configured with an XA driver -->

    <JDBCConnectionPool CapacityIncrement="1"

        DriverName="weblogic.jdbc.sqlserver.SQLServerDriver"

        InitialCapacity="5" MaxCapacity="50" Name="auxPool"

	 Properties="user=<yourUsername>;ServerName=<TNSNAME>;

	 PortNumber=<port>" Password="<yourPassword>"

        Targets="<yourServerName>"

        URL="jdbc:bea:sqlserver://<dbHostMachineName>:<port>"/>

 

<!-- This pool has been configured with an XA driver.  As for all XA pools, only one TxDataSource may connect to it.  In this case, it's the  'commercePool' TxDataSource -->

    <JDBCConnectionPool CapacityIncrement="1"

        DriverName="weblogic.jdbcx.sqlserver.SQLServerDataSource"

        KeepXAConnTillTxComplete="true"

        InitialCapacity="5" MaxCapacity="20" Name="portalPool"

	 Properties="user=<yourUsername>;ServerName=<TNSNAME>;

	 PortNumber=<port>" Password="<yourPassword>"

        Targets="<yourServerName>"

        URL="jdbc:bea:sqlserver://<dbHostMachineName>:<port>"/>

<!-- This pool has been configured with an XA driver.  As for all XA pools, only one TxDataSource may connect to it.  In this case, it's the  'contentDataSourcl' TxDataSource -->

    <JDBCConnectionPool CapacityIncrement="1"

        DriverName="weblogic.jdbcx.sqlserver.SQLServerDataSource"

        KeepXAConnTillTxComplete="true"

        InitialCapacity="5" MaxCapacity="15" Name="contentPool"

	 Properties="user=<yourUsername>;ServerName=<TNSNAME>;

	 PortNumber=<port>" Password="<yourPassword>"

        Targets="<yourServerName>"

        URL="jdbc:bea:sqlserver://<dbHostMachineName>:<port>"/>

<!-- This pool has been configured with an XA driver.  As for all XA pools, only one TxDataSource may connect to it.  In this case, it's the  ''portalFrameworkPool" TxDataSource  -->

    <JDBCConnectionPool CapacityIncrement="1"

        DriverName="weblogic.jdbcx.sqlserver.SQLServerDataSource"

        KeepXAConnTillTxComplete="true"

        InitialCapacity="5" MaxCapacity="20" Name="portalFrameworkPool"

	 Properties="user=<yourUsername>;ServerName=<TNSNAME>;

	 PortNumber=<port>" Password="<yourPassword>"

        Targets="<yourServerName>"

        URL="jdbc:bea:sqlserver://<dbHostMachineName>:<port>"/>

<!-- First, the non-XA data sources.  These must only point to 'auxPool' -->

    <JDBCDataSource

        JNDIName="p13n.trackingDataSource"

        Name="p13n_trackingDataSource" PoolName="auxPool" Targets="portalServer"/>

    <JDBCDataSource JNDIName="p13n.sequencerDataSource"

        Name="p13n_sequencerDataSource" PoolName="auxPool" Targets="portalServer"/>

    <JDBCDataSource

        JNDIName="p13n.dataSyncDataSource"

        Name="p13n_dataSyncDataSource" PoolName="auxPool" Targets="portalServer"/>

<!-- Although ebusiness can't partipate in XA, it must still use a TxDataSource (because of it uses EJBs), and point to the non-XA pool -->

    <JDBCTxDataSource

        JNDIName="weblogic.jdbc.jts.ebusinessPool" Name="ebusinessPool"

        PoolName="auxPool" Targets="portalServer"/>

<!-- Next, the XA data sources.  Each one must point to its own connection pool -->

    <JDBCTxDataSource

        JNDIName="weblogic.jdbc.jts.commercePool" Name="commercePool"

        PoolName="portalPool" Targets="portalServer"/>

    <JDBCTxDataSource

        JNDIName="contentDataSource" Name="contentDataSource"

        PoolName="contentPool" Targets="portalServer"/>

    <JDBCTxDataSource

        JNDIName="portalFrameworkPool" Name="portalFrameworkPool"

        PoolName="portalFrameworkPool" Targets="portalServer"/>

<!-- The JMS data stores should all point to the non-XA pool and have a null prefix -->

     <JMSJDBCStore ConnectionPool="auxPool" Name="cgJMSStore" PrefixName=""/>

</Domain>

XA for Sybase in a Portal Domain

For XA transaction support, install the license for Distributed Transaction Management (DTM) and configure the Sybase server as follows:

	sp_configure "enable DTM",1

go

	sp_configure "enable xact coordination",1

go

           	sp_configure "dtm lock timeout",30

go

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. See the "Using Adaptive Distributed Transaction Features" Sybase product manual for additional information.

To prevent deadlocks when running transactions, enable row level locking by default:

  	sp_configure "lock scheme",0,datarows

go