JPA and OSGi Applications

You can use Java™ Persistence API (JPA) in OSGi Applications in a similar way to JPA in Java EE applications. This topic describes the differences when you 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 that contains 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 that are 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.

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

For more information 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 Java Naming and Directory Interface (JNDI) lookup, a JNDI lookup to the service registry, or through Blueprint. This behavior is instead of the Java Naming and Directory Interface (JNDI) lookups that are 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="https://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, you 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, you can inject persistence contexts and units by using annotations or a blueprint extension.

You can inject persistence contexts and units by 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.

You can inject persistence contexts and units by 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 that an EntityManagerFactory instance is made available in the service registry for each persistence unit that is 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.