JPA and OSGi Applications

Use Java Persistence API (JPA) in OSGi Applications in a similar way to JPA in Java EE applications. This topic describes the differences when we use JPA with persistence bundles in an OSGi application.

OSGi applications use persistence bundles to define the entities and services that other bundles, or the persistence bundle itself, can use.

A persistence bundle is an OSGi bundle containing one or more persistence descriptors (persistence.xml files) and has a Meta-Persistence header in the bundle manifest, META-INF/MANIFEST.MF. This header lists all the locations of persistence.xml files in the persistence bundle. When this header is present, the default location, META-INF/persistence.xml, is added by default. Therefore, when the persistence.xml files are in the default location, the Meta-Persistence header must be present, but its content can be empty (a single space).

The following example of a Meta-Persistence header defines a persistence bundle with two persistence descriptors, one in entities and one in the nested jar lib/thirdPartyEntities.jar. Any persistence.xml files in the default location can also be used.

Meta-Persistence: entities/persistence.xml, 
lib/thirdPartyEntities.jar!/META-INF/persistence.xml

JPA support for OSGi applications can be container-managed or application-managed. Unmanaged JPA is not supported for OSGi applications.

Use JPA in web application bundles (WABs) in the same way that we use JPA in web application archives (WAR files), provided that all the persistence logic is contained in the web application.

See the following sections, and the related topic about developing applications that use JPA.

Persistence descriptors

In persistence.xml files for an OSGi application, the jta-data-source and non-jta-data-source elements access the data sources through a JNDI lookup, a JNDI lookup to the service registry, or through Blueprint. This behavior is instead of the JNDI lookups used in Java EE applications. The following examples show the syntax for a jta-data-source element:

<jta-data-source>
   jndi_name_of_the_data_source
</jta-data-source>

<jta-data-source>
   osgi:service/javax.sql.DataSource/(osgi.jndi.serviceName=
      jndi_name_of_the_data_source)
</jta-data-source>

The following example shows how to configure the JNDI name of a data source when the data source configuration uses a Blueprint resource reference.

<jta-data-source>
   blueprint:comp/blueprint_component_name
</jta-data-source>

The following example shows how the data source that uses a Blueprint resource reference is configured:

<blueprint xmlns="..." ... 
   xmlns:rr="http://www.ibm.com/appserver/schemas/8.0/blueprint/
   resourcereference">
   <rr:resource-reference id="blueprint_component_name" 
      interface="javax.sql.DataSource" 
      filter="(osgi.jndi.service.name=jndi_name_of_the_data_source)">
   <rr:res-auth>Container</rr:res-auth>
   <rr:res-sharing-scope>Shareable</rr:res-sharing-scope>
   </rr:resource-reference>
</blueprint>

To specify which version of a persistence provider is accepted, we can use a custom property in the persistence.xml file, as shown in the following example:

<persistence-unit name="myPU">
   <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
   <properties>
      <property name="org.apache.aries.jpa.provider.version" 
         value="[1.1.0,1.3.0]" />
   </properties>
</persistence-unit>

Container-managed JPA

For Blueprint bundles, we can inject persistence contexts and units using annotations or a blueprint extension.

We can inject persistence contexts and units using @PersistenceUnit and @PersistenceContext annotations on a blueprint bean. Injection through annotation is supported only for blueprint-managed components.

The Apache Aries JPA container context bundle provides the following Blueprint namespace for dependency injection of managed JPA resources:

http://aries.apache.org/xmlns/jpa/v1.0.0.

We can inject persistence contexts and units using Blueprint tags from this namespace. For example:

<blueprint xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0" ...>
   ...
   <bean name="myPersistenceBean" class="...">
      <jpa:unit property="emf" unitname="myPU" />
   </bean>
   ...
</blueprint>

Application-managed JPA

The OSGi JPA specification requires an EntityManagerFactory instance is made available in the service registry for each persistence unit defined in the persistence descriptors.

The EntityManagerFactory service has three notable service properties:

osgi.unit.name

The name of the persistence unit for the EntityManagerFactory service.

osgi.unit.version

The version of the persistence bundle.

osgi.unit.provider

The name of the persistence provider implementation class for the EntityManagerFactory service.

Related:

Resource references and the Blueprint Container

Enterprise OSGi standards

Develop applications that use the Java Persistence API

OSGi Service Platform Release 4 Version 4.2 Enterprise Specification

Example: OSGi bundle manifest file

Converting a persistence archive file to an OSGi bundle

File name: was332.html

prettyPrint();