JPA : Usage of DataNucleus within an OSGi environment

DataNucleus jars are OSGi bundles, and as such, can be deployed in an OSGi environment. Being an OSGi environment care must be taken with respect to class-loading. In particular the persistence property datanucleus.primaryClassLoader will need setting. Please refer to the following guide(s) for assistance until a definitive guide can be provided

An important thing to note : any dependent jar that is required by DataNucleus needs to be OSGi enabled. By this we mean the jar needs to have the MANIFEST.MF file including ExportPackage for the packages required by DataNucleus. Failure to have this will result in ClassNotFoundException when trying to load its classes.

Use jdo-api.jar v3.0.1 or later since those are OSGi-enabled. Also the Geronimo "jpa" jar that is included in the DataNucleus distribution is OSGi enabled too.

When using DataNucleus in an OSGi environment you can set the persistence property datanucleus.plugin.pluginRegistryClassName to org.datanucleus.plugin.OSGiPluginRegistry.


JPA and OSGi

In a non OSGi world the persitence provider implementation is loaded using the service provider pattern. The full qualified name of the implementation is stored in a file under META-INF/services/javax.persistence.spi.PersistenceProvider (inside the jar of the implementation) and each time the persistence provider is required it gets loaded with a Class.forName using the name of the implementing class found inside the META-INF/services/javax.persistence.spi.PersistenceProvider. In the OSGi world that doesn't work. The bundle that needs to load the persistence provider implementation cannot load META-INF/services/javax.persistence.spi.PersistenceProvider. A work around is to copy that file inside each bundle that requires access to the peristence provider. Another work around is to export the persistence provider as OSGi service. This is what the DataNucleus JPA jar does.

Further reading available on this link


Sample using OSGi and JPA

If you go to DataNucleus sample downloads you will find a sample called datanucleus-samples-osgi-jpa. This provides a simple example that you can build and load into such as Apache Karaf to demonstrate JPA persistence. Here we attempt to highlight the key aspects specific to OSGi in this sample.

Model classes are written in the exact same way as you would for any application.

Creation of the EMF is specified in a persistence-unit as normal except that we need to provide two overriding properties

        Map<Object, Object> overrideProps = new HashMap();
        overrideProps.put("datanucleus.primaryClassLoader", this.getClass().getClassLoader());
        overrideProps.put("datanucleus.plugin.pluginRegistryClassName", "org.datanucleus.plugin.OSGiPluginRegistry");

        EntityManagerFactory emf = Persistence.createEntityManagerFactory("PU", overrideProps);

so we have provided a class loader for the OSGi context of the application, and also specified that we want to use the OSGiPluginRegistry.

All persistence and query operations using EntityManager etc thereafter are identical to what you would use in a normal JSE/JEE application.

The pom.xml also defines the imports/exports for our OSGi application bundle, so look at this if wanting guidance on what these could look like when using Maven and the "felix bundle" plugin.

If you read the file README.txt you can see basic instructions on how to deploy this application into a fresh download of Apache Karaf, and run it. It makes uses of Spring DM to start the JPA "application".