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 13.

Figure 13. Creating the Auto-Enlisting XA Wrapper

The derby-ds bundle shown in Figure 13 encapsulates the code from Example 20, 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.

Instantiation of the data source proxy depends on the Aries transaction wrapper bundle (org.apache.aries.transaction.wrappers bundle). The Aries transaction wrapper bundle defines an activator, which installs hooks into the OSGi runtime, so that it gets notified whenever an OSGi bundle exports a service supporting the javax.sql.XADataSource interface.

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.

If you deploy the derby-ds bundle, you can see how the wrapper proxy is automatically created. For example, after following the instructions in Define a Derby Datasource and 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:

In Spring XML, you can access the auto-enlisting data source proxy by defining an osgi:reference element as shown in Example 21.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:osgi="http://www.springframework.org/schema/osgi"
       xsi:schemaLocation="
   http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans.xsd
   http://www.springframework.org/schema/osgi  
       http://www.springframework.org/schema/osgi/spring-osgi.xsd    
">

    <!--
        Import Derby XA data source as an OSGi service
    -->
    <osgi:reference id="derbyXADataSource"
                    interface="javax.sql.DataSource"
                    filter="(datasource.name=derbyXADB)"/>

</beans>

This example exploits the fact that the data source proxy exposes a different interface to the original data source (javax.sql.DataSource instead of javax.sql.XADataSource), which enables us to distinguish between the two data sources. In some cases, however, you might need to filter based on the aries.xa.aware property as well. For example:

filter="(&(datasource.name=derbyXADB)(aries.xa.aware=true))"

In blueprint XML, you can access the auto-enlisting data source proxy by defining an reference element as shown in Example 22.

<?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>

Additional configuration options (Table 13) for controlling the pooling of JDBC connections are available for a JDBC driver that is auto-enlisted in the Aries transaction manager. In the Spring or 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>