Red Hat Training

A Red Hat training course is available for Red Hat Fuse

10.3. Define a Derby Datasource

Overview

This section explains how to define a Derby datasource (and database instance), package the datasource as an OSGi bundle, and export the datasource as an OSGi service.

Derby data source implementations

Derby provides a variety of different data source implementations, as described in Derby data sources. For XA transactions, there are two alternatives: EmbeddedXADataSource (where the database instance runs in the same JVM) and ClientXADataSource (where the application connects to a remote database instance). The current example uses EmbeddedXADataSource.

Auto-enlisting an XA data source

In practice, you need to wrap the basic Derby data source with an object that performs auto-enlisting of the XA data source. Apache Aries provides such a wrapper layer. In order to trigger the wrapper mechanism, however, you must export the Derby data source as an OSGi service as described in Apache Aries Auto-Enlisting XA Wrapper (and as is done in the current example).

Prerequisites

Before using Derby in the OSGi container, you must integrate Derby with the container, as described in Section 10.2, “Integrate Derby with JBoss Fuse”.

Steps to define a Derby datasource

Perform the following steps to define a Derby datasource packaged in an OSGi bundle:
  1. Use the quickstart archetype to create a basic Maven project. Maven provides archetypes, which serve as templates for creating new projects. The Maven quickstart archetype is a basic archetype, providing the bare outline of a new Maven project.
    To create a new project for the Derby datasource bundle, invoke the Maven archetype plug-in as follows. Open a new command prompt, change directory to a convenient location (that is, to the directory where you will store your Maven projects), and enter the following command: 
    mvn archetype:generate
  -DarchetypeArtifactId=maven-archetype-quickstart
  -DgroupId=org.fusesource.example
  -DartifactId=derby-ds
    Note
    The preceding command parameters are shown on separate lines for ease of reading. You must enter the entire command on a single line, however.
    After downloading the requisite dependencies to run the quickstart archetype, the command creates a new Maven project for the org.fusesource.example/derby-ds artifact under the derby-ds directory.
  2. Change the project packaging type to bundle. Under the derby-ds directory, open the pom.xml file with a text editor and change the contents of the packaging element from jar to bundle, as shown in the following highlighted line: 
    <project ...>
  ...
  <groupId>org.fusesource.example</groupId>
  <artifactId>derby-ds</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>bundle</packaging>
  ...
</project>
  3. Add the bundle configuration to the POM. In the pom.xml file, add the following build element as a child of the project element: 
    <project ...>
  ...
  <build>
    <defaultGoal>install</defaultGoal>

    <plugins>

      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
          <instructions>
            <Bundle-SymbolicName>${project.groupId}.${project.artifactId}</Bundle-SymbolicName>
          </instructions>
        </configuration>
      </plugin>
      
    </plugins>
  </build>

</project>
  4. Customize the Maven compiler plug-in to enforce JDK 1.7 coding syntax. In the pom.xml file, add the following plugin element as a child of the plugins element, to configure the Maven compiler plug-in: 
    <project ...>
  ...
  <build>
    <defaultGoal>install</defaultGoal>

    <plugins>
     <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.7</source>
          <target>1.7</target>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>

</project>
  5. Add the Derby dependency to the POM and add the derby-version property to specify the version of Derby you are using. In the pom.xml file, add the derby-version element and the dependency element as shown: 
    <project ...>
  ...
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <derby-version>10.10.1.1</derby-version>
  </properties>

  <dependencies>
    <!-- Database dependencies -->
    <dependency>
      <groupId>org.apache.derby</groupId>
      <artifactId>derby</artifactId>
      <version>${derby-version}</version>
    </dependency>

    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  ...
</project>
    Important
    Remember to customize the derby-version property to the version of Derby you are using.
  6. Instantiate the Derby database instance and export the datasource as an OSGi service. In fact, this example exports two datasources: an XA datasource and a non-transactional datasource. The Derby datasources are exported using a blueprint XML file, which must be stored in the standard location, OSGI-INF/blueprint/. Under the derby-ds project directory, create the dataSource.xml blueprint file in the following location: 
    src/main/resources/OSGI-INF/blueprint/dataSource.xml
    Using your favorite text editor, add the following contents to the dataSource.xml file: 
    <?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">
   </service-properties>
  </service>
  
  <bean id="derbyDataSource" class="org.apache.derby.jdbc.EmbeddedDataSource">
    <property name="databaseName" value="txXaTutorial">
  </bean>
  
  <service ref="derbyDataSource" interface="javax.sql.DataSource">
   <service-properties>
     <entry key="datasource.name" value="derbyDB">
   </service-properties>
  </service>
</blueprint>
    In the definition of the derbyXADataSource bean, the databaseName property identifies the database instance that is created (in this case, txXaTutorial).
    The first service element exports the XA datasource as an OSGi service with the interface, javax.sql.XADataSource. The following service properties are defined:
    datasource.name
    Identifies this datasource unambiguously when it is referenced from other OSGi bundles.
    aries.xa.name
    Defines a unique XA resource name, which is used by the Aries transaction manager to identify this JDBC resource. This property must be defined in order to support XA recovery.
    The second service element defines a non-transactional datasource as an OSGi service with the interface javax.sql.DataSource.
  7. To build the derby-ds bundle and install it in the local Maven repository, enter the following Maven command from the derby-ds directory: 
    mvn install