OSGi and JPA

Tutorial: Using JPA in an OSGi Environment

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: org.knowhowlab.tips.jpa.model


• 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


- hibernate.hbm2ddl.auto - database generation mode


  • hibernate.connection.url - database connection URL



Dmytro  Pishchukhin
Dmytro Pishchukhin

What do you think?

JAX Magazine - 2014 - 06 Exclucively for iPad users JAX Magazine on Android


Latest opinions