A JDBC client can access an XA data source either directly, through the javax.sql.XADataSource interface, or indirectly, through a proxy object that implements the javax.sql.DataSource interface. In the context of OSGi, the usual way to integrate an XA data source is to instantiate the data source implementation provided by the underlying database and then to export that data source as an OSGi service.

The javax.sql.DataSource interface is the preferred way to expose a JDBC interface. It is a highly abstracted interface, exposing only two methods, getConnection and setConnection, to the JDBC client.

According to the JDBC specification, the usual way to make a DataSource object available to a JDBC client is through the JNDI registry.

In the context of XA transactions, a JDBC data source can be exposed as a javax.sql.XADataSource object. The main difference between an XADataSource object and a plain DataSource object is that the XADataSource object returns a javax.sql.XAConnection object, which you can use to access and enlist an XAResource object.

By default, enlisting an XAResource object is a manual procedure. That is, when using an XADataSource directly, a JDBC client must explicitly write the code to obtain the XAResource and enlist it with the current transaction. An alternative approach is to wrap the XA data source in a proxy data source that performs enlistment automatically (for example, see Apache Aries Auto-Enlisting XA Wrapper).

The JDBC specification mandates that a data source implementation class implements the bean properties shown in Table 8. These properties are not defined on the javax.sql.DataSource interface and need not all be implemented. The only required property is description.

	Note
	Although the properties shown in this table are standardized, they are not compulsory. A given data source implementation might define some or all of the standard properties, and is also free to define additional properties not mentioned in the specification.

Apache Derby is an open source database implementation, which provides a full implementation of XA transactions. In the current document, we use it as the basis for some of our examples and tutorials.

	Important
	Apache Derby is neither maintained nor supported by FuseSource. No guarantees are given with respect to the robustness or correctness of its XA implementation. It is used here solely for the purposes of illustration.

Apache Derby provides the following alternative data source implementations (from the org.apache.derby.jdbc package):

	Note
	If you need to gain access to the additional API methods defined in the JDBC 4.0 specification (such as isWrapperFor), use the variants of these data source classes with 40 appended. For example, EmbeddedDataSource40, EmbeddedXADataSource40, and so on.

Table 9 shows the properties supported by the Derby data sources. For basic applications, the databaseName property (which specifies the database instance name) is the most important one.

The JDBC specification recommends that data source objects are provided through the JNDI registry. In the context of the OSGi container, however, the natural mechanism for enabling loose coupling of services is the OSGi service registry. For this reason, the examples here show you how to create an XA data source and expose it as an OSGi service.

	Note
	Additionally, exposing a data source as an OSGi service has the advantage that it integrates automatically with the Aries XA data source wrapper layer. See Apache Aries Auto-Enlisting XA Wrapper.

In Spring XML, you can expose a Derby XA data source as an OSGi service using the code shown in Example 17.

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

  <bean id="derbyXADataSource" class="org.apache.derby.jdbc.EmbeddedXADataSource">
    <property name="databaseName" value="txXaTutorial"/>
  </bean>

  <osgi:service ref="derbyXADataSource" interface="javax.sql.XADataSource">
   <osgi:service-properties>
     <entry key="osgi.jndi.service.name" value="jdbc/derbyXADB"/>
     <entry key="datasource.name" value="derbyXADB"/>
   </osgi:service-properties>
  </osgi:service>

</beans>

In this example, the Derby database runs as an embedded instance in the current bundle, where the name of the database instance is txXaTutorial. The exported OSGi service defines two service properties: osgi.jndi.service.name and datasource.name. These properties can be used to disambiguate the data sources, in case multiple data sources are exposed as OSGi services.

	Note
	Additionally, you must set the requisite Java system properties for Derby in the OSGi container (not shown here). For details, see Integrate Derby with Fuse ESB Enterprise.

In blueprint XML, you can expose a Derby XA data source as an OSGi service using the code shown in Example 18.

<?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="osgi.jndi.service.name" value="jdbc/derbyXADB"/>
     <entry key="datasource.name" value="derbyXADB"/>
   </service-properties>
  </service>
  
</blueprint>

For more information about defining Derby data sources, see the Apache Derby manuals.