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:


Eclipse Gemini

Short overview of the tutorial steps

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

• 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)


– 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:
  •   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


• OpenJPA profile:


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

– add to imported packages:


– enhance model classes with


– add OpenJPA-specific properties to


- 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:


  •   run command:
    mvn clean install -P hibernate


  •   details:


– add to imported packages:


– add Hibernate-specific properties
to persistence.xml:


- hibernate.dialect – database


- hibernate.hbm2ddl.auto – database
generation mode


  • hibernate.connection.url – database
    connection URL


JPA client bundle


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

• lsgrps – print group records

• delgrp <id> – delete group
record by ID

• delstud <id> – delete
student record by ID

• addgrp <name> – add group

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



Gemini with EclipseLink


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


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


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.





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


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


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. ops4j.org and www.knowhowlab.org. Dmytro currently resides in Frankfurt am Main, Germany.
comments powered by Disqus