XA support in Apache Aries JPA

Prerequisite is to have a correctly wrapped DataSource or DataSourceFactory like described above.

The next thing is to create a bundle for the JPA Entities. For the most part, this works like in JEE. The entities need to be correctly annotated and a persistence.xml should be put into META-INF/persistence. The main thing to keep in mind for OSGi is to add a special Manifest header Meta-Persistence: META-INF/persistence.xml which marks the bundle as containing a persistence unit and points to the location of the persistence.xml.

Aries JPA will monitor all bundles in state Starting and Active for the Meta-Persistence header above. It will then scan the persistence.xml and create a matching EntityManagerFactory and also an EntityManager as an OSGi service.

These services can then be leveraged in a second bundle that uses JPA to access the entities. The easiest way to do this is to leverage the blueprint-maven-plugin. It scans the classes for CDI/JEE annotations and creates a blueprint xml from them. The skeleton of a class using JPA would look like this:

@Singleton
@Transactional
public class BookRepositoryImpl {
    @PersistenceContext(unitName="ebook")
    EntityManager em;
}

@Singleton marks the class as a bean to be listed in the blueprint.xml. This is the major difference to CDI where it is not needed to mark beans in a special way.

@Transactional can be used on class or method level. An annotation on method level overrides the same on class level. By default, this will define a transaction of type TxType.Required. This is the typical type for methods that change JPA entities. It defines that the method will join a transaction if one exists, or create a new one if needed. For methods that only read data, the TxType.Supports can be used. It allows the method to participate in a transaction but also to run without. For a full description of the annotation, set the JTA 1.2 specification.

@PersistenceContext defines that the variable should be injected with the EntityManager of the named persistence unit. Aries JPA takes care of creating thread safe EntityManager that can be used like in JEE. The lifecycle of the EntityManager is bound to an OSGi Coordination. By default, the coordination spans that outermost call marked with @Transactional. This is important as the EntityManager itself is not thread safe, so Aries JPA internally needs to bind one instance to a thread but also needs to make sure the EntityManager is relatively short lived to avoid class loading problems in case of bundle restarts.

The user can also create a Coordination manually using the CoordinatorService. In the ebook example, this is done using a CXF interceptor that creates the coordination on the CXF level when a request is received and only ends it when the serialization is done. This makes the EntityManager available during serialization and allows to lazily load entities without the problem of having detached entities.