8.2. Apache Aries Auto-Enlisting XA Wrapper

Overview

One of the features of the Apache Aries transaction module is that it provides support for auto-enlistment of XA transactions in the context of JDBC data sources. As already noted, auto-enlisting is the most practical way of integrating an XA data source with a transaction manager. The basic idea is to wrap the original data source with a data source proxy object that encapsulates the logic to perform auto-enlisting.
An unusual aspect of the Apache Aries' auto-enlisting feature is that the data source proxy is automatically created for you. In order to trigger auto-creation of the data source proxy, it is necessary to export your data source as an OSGi service. The mechanism is illustrated in Figure 8.1, “Creating the Auto-Enlisting XA Wrapper”.

Figure 8.1. Creating the Auto-Enlisting XA Wrapper

Creating the Auto-Enlisting XA Wrapper

derby-ds bundle

The derby-ds bundle shown in Figure 8.1, “Creating the Auto-Enlisting XA Wrapper” encapsulates the code from Example 8.1, “Exposing XA DataSource as an OSGi Service in Blueprint XML”, which defines a Derby XA data source and exports it as an OSGi service.
Also shown wthin the scope of the derby-ds bundle is the auto-enlisting data source proxy. But this data source proxy is not created by the code in the derby-ds bundle and is initially not part of the bundle.

Automatic wrapper instantiation

Instantiation of the data source proxy depends on the Aries transaction wrapper bundle (org.apache.aries.transaction.wrappers). This bundle defines an activator, which installs hooks into the OSGi runtime, so that it is notified whenever an OSGi bundle exports a service supporting the javax.sql.XADataSource interface.
Important
The Aries transaction wrapper bundle is not installed by default. To take advantage of the datasource wrapping functionality, you must explicitly install the connector feature.
To install it on a standalone JBoss Fuse container, use this command: 
JBossFuse:karaf@root> features:install connector
In fabric environments, you add the connector feature to the profile that is deployed to the container on which the JDBC driver will enlist with the Aries transaction manager.
You can add it to the jboss-fuse-full profile, using this command: 
JBossFuse:karaf@root> profile-edit --feature connector jboss-fuse-full
or add it to any user-defined profile, using this command: 
JBossFuse:karaf@root> profile-edit --feature connector <custom-profile-name>

XADataSourceEnlistingWrapper

Upon detecting a new OSGi service supporting the javax.sql.XADataSource interface, the activator automatically creates a new XADataSourceEnlistingWrapper object, which wraps the original XA data source, effectively acting as a data source proxy. The XADataSourceEnlistingWrapper object also obtains a reference to the JTA transaction manager service (from the org.apache.aries.transaction.manager bundle). Finally, the activator exports the XADataSourceEnlistingWrapper object with the javax.sql.DataSource interface.
JDBC clients now have the option of accessing the XA data source through this newly created data source proxy. Whenever a new database connection is requested from the data source proxy (by calling the getConnection method), the proxy automatically gets a reference to the underlying XA resource and enlists the XA resource with the JTA transaction manager. This means that the required XA coding steps are automatically performed and the JDBC client does not need to be XA transaction aware.
Note
The XADataSourceEnlistingWrapper class is not exported from the Aries transaction wrapper bundle, so it is not possible to create the data source proxy explicitly. Instances of this class can only be created automatically by the activator in the transaction wrapper bundle.

Accessing the enlisting wrapper

If you deploy the derby-ds bundle, you can see how the wrapper proxy is automatically created. For example, after following the instructions in Section 10.3, “Define a Derby Datasource” and Section 10.5, “Deploy and Run the Transactional Route” to build and deploy the derby-ds bundle, you can list the OSGi services exported by the derby-ds bundle using the osgi:ls console command. Assuming that derby-ds has the bundle ID, 229, you would then enter: 
JBossFuse:karaf@root> osgi:ls 229
The console produces output similar to the following: 
Derby XA data source (229) provides:
------------------------------------
datasource.name = derbyXADB
objectClass = javax.sql.XADataSource
osgi.jndi.service.name = jdbc/derbyXADB
osgi.service.blueprint.compname = derbyXADataSource
service.id = 423
----
aries.xa.aware = true
aries.xa.name = derbyDS
datasource.name = derbyXADB
objectClass = javax.sql.DataSource
osgi.jndi.service.name = jdbc/derbyXADB
osgi.service.blueprint.compname = derbyXADataSource
service.id = 424
----
...
The following OSGi services are exposed:
  • An OSGi service with interface javax.sql.XADataSource and datasource.name equal to derbyXADB—this is the XA data source explicitly exported as an OSGi service in Example 8.1, “Exposing XA DataSource as an OSGi Service in Blueprint XML”.
  • An OSGi service with interface javax.sql.DataSource and datasource.name equal to derbyXADB—this is the auto-enlisting data source proxy implicitly created by the Aries wrapper service. The data source proxy copies the user-defined service properties from the original OSGi service and adds the setting aries.xa.aware = true. The aries.xa.aware property enables you to distinguish between the generated proxy and the original data source.

Blueprint

In blueprint XML, you can access the auto-enlisting data source proxy by defining an reference element as shown in Example 8.2, “Importing XA DataSource as an OSGi Service Reference in Blueprint XML”.

Example 8.2. Importing XA DataSource as an OSGi Service Reference in Blueprint XML

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0"
            default-activation="lazy">
  
    <!--
        Import Derby XA data source as an OSGi service
    -->
    <reference id="derbyXADataSource"
                interface="javax.sql.DataSource"
                filter="(datasource.name=derbyXADB)"/>
</blueprint>

JDBC connection pool options

Additional configuration options (Table 8.3) for controlling the pooling of JDBC connections are available for a JDBC driver that is auto-enlisted in the Aries transaction manager. In the Blueprint datasource.xml, these options are specified as key/value pairs under the service definition's service-properties element.
For example, in the following Blueprint datasource.xml example, several of the connection pool configuration options are specified: 
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0"
            default-activation="lazy">
  
  <bean id="derbyXADataSource" class="org.apache.derby.jdbc.EmbeddedXADataSource">
    <property name="databaseName" value="txXaTutorial"/>
  </bean>

  <service ref="derbyXADataSource" interface="javax.sql.XADataSource">
   <service-properties>
     <entry key="datasource.name" value="derbyXADB"/>
     <!-- A unique ID for this XA resource. Required to enable XA recovery. -->
     <entry key="aries.xa.name" value="derbyDS"/>
     <!-- Additional supported pool connection properties -->
     <entry key="aries.xa.pooling" value="true"/>
     <entry key="aries.xa.poolMinSize" value="1"/>
     <entry key="aries.xa.poolMaxSize" value="3"/>
     <entry key="aries.xa.partitionStrategy" value="none"/>
     <entry key="aries.xa.allConnectionsEquals" value="false"/>
   </service-properties>
  </service>
  
  ...
  
</blueprint>

Table 8.3. JDBC connection pool configuration options

PropertyDescription
aries.xa.name Specifies the name of the managed resource that the transaction manager uses to uniquely identify and recover the resource.
aries.xa.exceptionSorter
(Optional) Determines whether an exception will cause the connection to be discarded and rollback of the transaction eventually attempted. Valid values are:
  • all—[Default] All exceptions considered fatal; discard the connection and attempt rollback.
  • none—No exception considered fatal; retain connection, no rollback
  • known—Only known SQL states not considered fatal; for those, retain connection/no rollback. For a list of known states, see KnownSQLStateExceptionSorter.
  • custom—Only the specified comma-separated list of SQL states not considered fatal; for those, retain connection/no rollback. For example,
    <entry key="aries.xa.exceptionSorter" value="custom(06S04,09S05)" />
aries.xa.username (Optional) Specifies the name of the user to use. This property is usually set on the inner ConnectionFactory. However, setting it in the service definition overrides the value set in the inner ConnectionFactory.
aries.xa.password (Optional) Specifies the password to use. This property is usually set on the inner ConnectionFactory. However, setting it also in the service definition overrides the value set in the inner ConnectionFactory.
aries.xa.pooling (Optional) Enables/disables support for pooling. Default is true (enabled).
aries.xa.poolMaxSize (Optional) Specifies the maximum pool size in number of connections. Default is 10.
aries.xa.poolMinSize (Optional) Specifies the minimum pool size in number of connections. Default is 0.
aries.xa.transaction
(Optional) Specifies the type of transactions to use. Valid values are:
  • none—No transactions used
  • xa—[Default] XA transactions used
  • local—Non XA transactions used
aries.xa.partitionStrategy
(Optional) Specifies the pool partitioning strategy to use. Valid values are:
  • none—[Default] No partitioning
  • by-subject—Partition by authenticated users
  • by-connector-properties—Partition by connection properties
aries.xa.connectionMadIdleMinutes[a](Optional) Specifies the maximum time, in minutes, that a connection can remain idling before it’s released from the pool. Default is 15.
aries.xa.connectionMaxWaitMilliseconds (Optional) Specifies the maximum time, in milliseconds, to wait to retrieve a connection from the pool. Default is 5000.
aries.xa.allConnectionsEquals
(Optional) Specifies to assume that all connections are equal— use the same user credentials—when retrieving one from the pool. Default is true.
Note: If you're using different kinds of connections to accommodate different users, do not enable this option unless you use a partition strategy that pools matching connections. Otherwise, attempts to retrieve connections from the pool will fail.
aries.xa.validateOnMatchSpecifies whether to check the validity of a connection at the time it is checked out of the connection pool. Defaults to true. Note that it is usually unnecessary to enable both the validateOnMatch option and the backgroundValidation option simultaneously.
aries.xa.backgroundValidationEnables background validation of connections in the pool. When this option is enabled, a separate thread runs in the background to check the validity of the connections in the pool. This is typically more efficient than the validateOnMatch option (and it is recommended that you set the validateOnMatch option to false when this option is enabled). Defaults to false.
aries.xa.backgroundValidationMillisecondsUsed in combination with the backgroundValidation option. Specifies the interval between background validation checks in units of milliseconds. Defaults to 600000 (10 minutes).
[a] Though the spelling of this property appears incorrect, it is not. Do not replace the d in connectionMadMinutes with an x.