OSGi Container Managed JPA

There are some tutorials and chapters out there on the net which describe how to setup JPA in OSGi but most described setups are too simple and can't be used in production.

My requirements are

  • Apache Karaf
  • PostgreSQL
  • JPA 2.0
  • JTA
  • Connection pool
  • Configurable database connection properties
This article describes a working setup and starting point to build upon which doesn't necessarily mean that it is the best solution for everybody.
This does not seem to work with nested transactions and OpenJPA 2.2.2! Instead use PAX-JDBC.

Apache Karaf

I am using the current stable Apache Karaf 3 branch, Apache Karaf 3.0.3.

I install certain features which I need for my setup:

feature:install scr webconsole jndi jdbc

Installed Features

I later need to have the following features installed:

transaction         | 1.1.1            | x         | enterprise-3.0.3        | OSGi Transaction Manager                          
jpa                 | 2.0.0            | x         | enterprise-3.0.3        | OSGi Persistence Container                        
openjpa             | 2.2.2            | x         | enterprise-3.0.3        | Apache OpenJPA 2.2.x persistence engine support   
jndi                | 3.0.3            | x         | enterprise-3.0.3        | OSGi Service Registry JNDI access                 
jdbc                | 3.0.3            | x         | enterprise-3.0.3        | JDBC service and commands  

JPA

Apache Karaf makes it very easy to add JPA support. Just install the feature:

feature:install jpa/2.0.0 openjpa/2.2.2

JTA

The transaction support is as easily installed as the JPA support.

feature:install transactions/1.1.1

Using Transactions

To use transactions in a service component and provide an EntityManager to that component the OSGi Blueprint service can be used. Just declare the Blueprint bean and expose it as an OSGi service.

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
	xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0" xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0">
    
	<bean id="contactPersonService" class="sdm.service.crm.ContactPersonService">
		<tx:transaction method="*" value="Required" />
		<jpa:context property="entityManager" unitname="sdm" />
	</bean>
	<service id="sdmContactPersonService" ref="contactPersonService" interface="sdm.api.IContactPersonService" />
</blueprint>

PostgreSQL

PostgreSQL doesn't supply a bundle for its driver but luckily the Apache Service Mix project repackages the database driver. It can be retrieved from the standard Maven repository.

http://search.maven.org/#search%7Cga%7C1%7Corg.apache.servicemix.bundles.postgresql

The bundle just needs to be dropped into the deploy folder for deployment.

The bundle needs to be started prior to the JPA stuff so the bundle start level needs to be set to a lower value.

bundle:start-level <postgres-bundle-id> 25

Data Sources

Data sources are created as OSGi services via blueprint. Create the blueprint.xml in a bundle in the folder OSGI-INF/blueprint. This is the default location which can be configured in the MANIFEST.MF, see manifest file entry Bundle-Blueprint.

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0"
	xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0" 
	xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0">

    <reference id="transactionManager" interface="javax.transaction.TransactionManager" />
    
    <!-- Configuration Admin suppport -->
    <cm:property-placeholder persistent-id="sdm.persistence.datasource" update-strategy="reload" />

    <bean class="org.postgresql.xa.PGXADataSource" id="xaDatasource">
        <property name="serverName" value="${host}" />
        <property name="databaseName" value="${database}" />
        <property name="user" value="${user}" />
        <property name="password" value="${password}" />
    </bean>
    
    <bean class="org.apache.commons.dbcp2.managed.BasicManagedDataSource" id="xaSdsDatasource" destroy-method="close">
        <property name="xaDataSourceInstance" ref="xaDatasource" />
        <property name="transactionManager" ref="transactionManager" />
        <property name="maxTotal" value="25" />
        <property name="initialSize" value="3" />
    </bean>

	<service id="xaSdsDS" interface="javax.sql.DataSource" ref="xaSdsDatasource">
		<service-properties>
			<entry key="osgi.jndi.service.name" value="jdbc/xasds" />
		</service-properties>
	</service>
	
</blueprint>

Connection Pooling

I am using the PostgreSQL XA datasource as a base data source and configure the BasicManagedDataSource from the commons-dbcp2 to use it as a data source for retrieving connections:

<property name="xaDataSourceInstance" ref="xaDatasource" />

Configurable database connection properties

The database connection properties are configured via the OSGi ConfigAdmin service.

The configuration file sdm.persistence.database.cfg need to be created in the <karaf_home>/etc folder.

service.pid=sdm.persistence.datasource
host=dbserver
database=dbname
user=dbuser
password=dbsecret

To tell blueprint to use the configuration from this configuration the following line was added to the blueprint.xml file.

<cm:property-placeholder persistent-id="sdm.persistence.datasource" update-strategy="reload" />

Now the configuration can be accessed by its keys like ${host} and it doesn't have to be packaged with the bundles.

Parameters like maxTotal and initialSize needs to be adjusted to the environment.

Needed Bundles

For connection pooling the projects commons-dbcp2 and commons-pool2 are needed which already package their software as bundles and can be retrieved from the standard Maven repository.

I have used

  • commons-pool2 2.4.1
  • commons-dbcp2 2.1

persistence.xml

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0"
	xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">

	<persistence-unit name="sdm" transaction-type="JTA">
		<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>

		<jta-data-source>osgi:service/jdbc/xasds</jta-data-source>

		<class>sdm.data.Entity</class>

		<properties>
			<property name="openjpa.Log" value="File=/tmp/org.apache.openjpa.log, DefaultLevel=TRACE" />
			<property name="openjpa.RuntimeUnenhancedClasses" value="supported" />
		</properties>

	</persistence-unit>

</persistence>

FAQ

Unsatisfied requirement(s): service:(service=javax.transaction.TransactionManager)

If the feature obr is installed prior to the installation of the feature openjpa it won't install the feature openjpa.

karaf@root()> feature:install obr

karaf@root()> feature:install openjpa

Error executing command: Can't install feature openjpa/0.0.0:

Can not resolve feature:

Unsatisfied requirement(s):

---------------------------

   service:(service=javax.transaction.TransactionManager)

      Apache Aries Transaction Blueprint