OSGi and JPA

Tutorial: Using JPA in an OSGi Environment


Developing and running JPA code in diverse OSGi environments.

The tutorial below is a simple guide to developing and running JPA code in diverse OSGi environments (Eclipse Equinox, Apache Felix, Knopflerfish) with various JPA providers (Hibernate, EclipseLink, OpenJPA) and OSGi Enterprise API implementations (Apache Aries, Eclipse Gemini).

If you are interested in the source code used in this tutorial, please, refer to GitHub.


JPA and OSGi: known facts:

The Java Persistence API (JPA) is a specification that provides developers with a way to map objects to managing relational data in Java based environments. JPA is a part of Java Enterprise Edition 5 and 6 the latest version of which is 2.0. There are three broadly-known JPA open-source providers in the market:

1. Hibernate

2. EclipseLink

3. OpenJPA

The JPA Service Specification was first introduced in OSGi Enterprise Specification 4.2 in March 2010. Afterwards, the Apache and Eclipse communities presented their implementations of the OSGi Enterprise Specifications:

Apache Aries

Eclipse Gemini

Short overview of the tutorial steps

Beneath, is a list of the steps that are implemented in this tutorial:

• development of JPA model OSGi bundle with persistence.xml

• JPA model bundle tuning for different JPA providers

• development of JPA client bundle

• bundles configuration for Eclipse Gemini with EclipseLink

• bundles configuration for Apache Aries with OpenJPA

• build Hibernate OSGi bundle

• bundles configuration for Apache Aries with Hibernate

• build EclipseLink activation bundle

• bundles configuration for Apache Aries with EclipseLink

• bundles configuration for standalone EclipseLink


JPA model bundle description

To make our description more comprehensible and vivid let’s dwell on our tutorial model.

I should mention that this model is a simple structure of two classes (Student and Group – Listing 1) that are linked to each other in one-too-many bi-directional way. JPA 2.0 annotations are used to describe persistence entities and named queries.

Here we add a persistence description file (persistence.xml – Listing 2). It contains the list of model classes and some tutorial-specific settings:


• transaction-type=”RESOURCE_LOCAL” – to set transaction type explicitly. (The tutorial does not cover any optional functionality like external transaction managers)


• <exclude-unlisted-classes>true</exclude-unlisted-classes> – to disable scanning of persistence unit by persistence provider and attach only classes that are explicitly listed.


The file should be stored under META-INF/persistence.xml path. The next step for the model is to pack all classes into OSGi bundle. (maven-bundle-plugin configuration – Listing 3). The most important OSGi MANIFEST headers are:


• Import-Package should contain javax.persistence;version =”1.1.0″;jpa=”2.0″ to import JPA packages with required JPA version


• Export-Package should export model package:


• Meta-Persistence: META-INF/persistence.xml – is a relative path to persistence description file


• Import-Package could contain used JDBC driver package (in our case, this is org.apache.derby.jdbc). As an alternative, this package could be imported by client bundle to decouple model from JDBC drivers.



Every JPA provider needs minor fine-tuning of the model bundle. Maven profiles were added to meet these requirements:


• EclipseLink profile:


  •   name: eclipselink
  •   run command: mvn clean install -P eclipselink
  •   details:

– add to imported packages: org.eclipse.persistence. indirection


– add EclipseLink-specific properties to persistence.xml:


– javax.persistence.jdbc.driver – database JDBC driver class name


– javax.persistence.jdbc.url – database-specific connection URL


– eclipselink.ddl-generation – database generation actions


  • eclipselink.ddl-generation.output-mode – database generation target


• OpenJPA profile:


  •   name: openjpa
  •   run command: mvn clean install -P openjpa
  •   details:

– add to imported packages: org.apache.openjpa.enhance,org.apache.openjpa.util


– enhance model classes with org.apache.openjpa.enhance.PCEnhancer


– add OpenJPA-specific properties to persistence.xml:


– javax.persistence.jdbc.driver – database JDBC driver class name


– javax.persistence.jdbc.url – database-specific connection URL


  • openjpa.jdbc.SynchronizeMappings – run mapping tool to create database


• Hibernate profile:


  •   name: hibernate


  •   run command: mvn clean install -P hibernate


  •   details:


– add to imported packages: org.hibernate.proxy,javassist.util.proxy


– add Hibernate-specific properties to persistence.xml:


– hibernate.dialect – database dialect


– – database generation mode


  • hibernate.connection.url – database connection URL


JPA client bundle description


A client bundle represents a simple console application that uses EntityManager to manipulate with the JPA entities that are provided by the model bundle. The application is integrated into OSGi frameworks console commands with universal shell adapters.


A list of available commands (they all are listed with console “help” command):


• lsstuds – print student records

• lsgrps – print group records

• delgrp <id> – delete group record by ID

• delstud <id> – delete student record by ID

• addgrp <name> – add group record

• addstud <first_name> <last_name> <group_id> – add student record


JPA Service Specification (OSGi Enterprise Specification) describes that EntityManagerFactory service should be registered for every pair: Persistence Unit and Persistence Provider. In the client bundle on every command call we use EntityManagerFactory service instance that is available in OSGi registry (Client code sample – Listing 4).

The client bundle OSGi configuration is represented below (maven-bundle-plugin configuration – Listing 5). The most important OSGi MANIFEST headers are as follows:


• Import-Package should contain javax.persistence;version=”1.1.0″;jpa=”2.0″ to import JPA packages with required JPA version


• Import-Package should contain model package:



Gemini with EclipseLink configuration


The Gemini JPA project depicts modular implementations of Java Persistence API technology. This project currently provides the integration with the EclipseLink JPA provider to support the OSGi JPA specification approach that clients can use to get JPA support in an OSGi framework. The latest released version 1.0RC1 (25 March 2011) requires JDBC Service Specification (implemented by Gemini DBAccess) to access database and supports only Equinox as OSGi framework. In Listing 6, you can find a list of configuration bundles:




Aries with OpenJPA configuration


The Aries project delivers a set of pluggable Java components enabling an enterprise OSGi application programming model. This includes implementations and extensions of application-focused specifications defined by the OSGi Alliance Enterprise Expert Group.


Apache OpenJPA is a Java persistence project at The Apache Software Foundation that can be used as a stand-alone POJO persistence layer or integrated into any Java EE compliant container and many other lightweight frameworks. Listing 7 shows a list of configuration bundles. All tests of this configuration are passed except Knopflerfish OSGi framework test. It failed with some class loading exception.




Aries with Hibernate configuration

Hibernate is an Object/Relational Mapping solution for Java environments. Hibernate EntityManager project implements the programming interfaces and lifecycle rules as defined by the JPA 2.0 specification.

In accordance with the fact that the Hibernate community does not supply Hibernate engine with OSGi bundle MANIFEST, we have to create it ourselves with maven-bundleplugin using a simpler version of configuration described by Peter Kriens (Listing 8).

The other point that we have to achieve is an activation of Hibernate Persistence Provider that will be available for Aries (Listing 9). Listing 10 shows a list of configuration bundles.



Aries with EclipseLink configuration


The Eclipse Persistence Services Project (EclipseLink) delivers a comprehensive open-source Java persistence solution. The EclipseLink JPA provides developers with a standards based Object-Relational persistence solution with additional support for many advanced features.


Though EclipseLink project delivers OSGi bundles, we have to activate EclipseLink Persistence Provider to make it available for Apache Aries (Listing 11). Listing 12 shows a list of configuration bundles.



Standalone EclipseLink


It is possible to use EclipseLink as a standalone OSGi JPA provider. This solution has been announced as deprecated since version 2.2.0 but it can be used as well, if you do not feel like adding any extra libraries to support JPA. One extra header has been added to the model bundle to make Persistence Units available for the following EclipseLink configuration: JPA-PersistenceUnits: jpa.students. You can see a list of configuration bundles in Listing 13.


Run configurations and tests result


One of the main goals of the tutorial is to prove, that there is a feasible and easy way to run the same JPA model and client bundles with various configurations.


In this tutorial five different JPA configurations were created and every configuration was tested with three OSGi frameworks. The configurations can be run with:


mvn -f pom_<configuration>.xml -P <osgi_framework>


Available configurations:


• gemini

• aries-eclipselink

• aries-openjpa

• aries-hibernate

• eclipselink

Available OSGi frameworks:

• equinox

• felix

• kf

The test results are depicted in Table 1.



Summing up everything above, I would like to emphasize that the presented tutorial is only a starting point to use JPA in your OSGi environment. Consequently, we can speak about plenty of things that can be added and tested with the provided configurations: JPA provider features (e.g. cache, external transactions etc.), OSGi Enterprise features (e.g. Blueprint, Data Source Factories, JNDI etc.) and support of different databases.



All Posts by DmytroPishchukhin

Dmytro Pishchukhin is a consultant with over a decade extensive experience in Java, JEE, OSGi. He took a part in many OSGi projects for different markets: automotive, telematics, smart-house, train industry. He is a member of open-source projects related to OSGi technologies: www. and Dmytro currently resides in Frankfurt am Main, Germany.

Inline Feedbacks
View all comments