Managed JPA in OSGiGetting the best of both worlds

Tim WardIBMSubmission 163

2

AGENDA

> JPA Basics

> OSGi Basics

> The JPA Service specification

> JPA in a container

> The Apache Aries JPA container

3

The JavaTM Persistence API

> JPA is a POJO based Object Relational Mapping Framework

– It defines an API for persisting objects into a Relational Database

– And an API for retreiving Objects from the database

> JPA provides a rich API for mapping arbitrarily complex objects to the underlying database tables

POJO

POJO

4

Commonly used terms> JPA provider

– A JPA implementation

> Managed Classes (Entities)– Objects that can be stored in

the database by a provider

> Persistence Unit– A set of JPA configuration

identifying a database and a set of managed classes

> EntityManagerFactory– A runtime object specified by

a persistence unit

> Persistence descriptor– An xml file that defines one or

more persistence units

> EntityManager– A runtime object used to persist

and retrieve POJOs

> Persistence Context– A bit like a “session” it refers to

an EntityManager and the objects it is currently managing

> Managed JPA– JPA with container managed

persistence context lifecycles

5

The Persistence Descriptor

> Defined by the “http://java.sun.com/xml/ns/persistence” schema – In JavaTM SE and EE it is called persistence.xml and lives in META-INF/

> A persistence descriptor contains one or more named persistence unit definitions– A persistence unit definition specifies:

Managed Classes The JPA provider to use (optional) The database configuration (optional) Provider specific properties (optional)

> A persistence unit with no database configuration is known as “incomplete”– The database configuration must be specified at runtime before a

persistence unit can be used

6

Using JPA in JavaTM SE

> The persistence descriptor, managed classes and JPA provider must all be on the application classpath

EntityManagerFactory emf =Persistence.createEntityManagerFactory("myUnit");

EntityManager em = emf.createEntityManager();em.getTransaction().begin();try { em.persist(persistableObject); em.getTransaction().commit();} catch (PersistenceException pe) { if (em.getTransaction.isActive()) em.getTransaction().rollback();} finally { em.close(); emf.close();}

7

What is OSGi?

> OSGi is a modularity framework for JavaTM that has a very different classpath– The unit of modularity is the Bundle (a jar with a special manifest)– There is strict versioning of bundles, their capabilities, and dependencies

> OSGi also defines a Service Registry through which Bundles can share services at runtime

> All the contents of a bundle are private unless explicitly shared– Sharing is typically on a per

package basis– Sharing requires both an export

and an import of the shared code

com.ibm.foo

com.ibm.foo.impl

Bundle Manifest

8

Problems when using JPA in OSGi

> The contents of a bundle are private!– Persistence descriptors cannot be found by the JPA provider– Managed Classes cannot be loaded by the provider– The API classes cannot load the JPA provider implementation

> An OSGi framework is a dynamic place– The JPA provider may be installed and started after the JPA application– The JPA provider may be stopped and uninstalled before the JPA application

> Standard JDBC database access is not usually possible in an OSGi environment (more ClassLoader issues)

9

The JPA Service Specification

> An OSGi specification for making JPA work in an OSGi framework

> Core concepts:

> Persistence Bundle– An OSGi bundle containing

managed classes a persistence descriptor and a Meta-Persistence manifest header

> Meta-Persistence header– A header that defines the

locations of persistence descriptors in a bundle

> EntityManagerFactory service– An EntityManagerFactory

available as an OSGi service

> Persistence Client– A bundle that makes use of an

EntityManagerFactory service.

> EntityManagerFactory builder– A factory for incomplete

persistence units

10

How to use JPA in OSGi (1)

> Add a Meta-Persistence: header to your bundle– An empty header defaults to /META-INF/persistence.xml

> When started, there will now be an EntityManagerFactory service registered for every complete persistence unit– This is dependent on the JPA service being started, and

the OSGi JDBC service providing the JDBC driver

> The EntityManagerFactoryBuilder service can be used once to supply or override configuration for a persistence unit– this still relies on the JDBC driver in the JDBC service

Meta-Persistence: OSGI-INF/jpa.xml

PersistenceBundle

EMF Service

EMFBuilder Service

11

How to use JPA in OSGi (2)

> Good News! The JavaTM SE code will still work using the OSGi Persistence class– But this is not good practice as it does not track the service lifecycle

> Proper practice is to use the OSGi service registry directly, but this adds 20+ lines of bootstrap for looking up and clearing up the service– It also adds an additional dependency on the OSGi API classes

> The EntityManagerFactoryBuilder is even more complex!– Clients need to track the JDBC driver service their persistence unit uses as

well as the persistence unit

PersistenceBundle

EMFBuilder Service

JDBC Driver Service

12

Limitations of the JPA Service specification

> The JPA service makes JPA possible in a simple way, but...– It requires a large amount of OSGi boilerplate to do properly– Even when taking OSGi shortcuts it still requires lots of JPA boilerplate– The static Persistence class encourages poor OSGi practice

> Using a dependency injection container reduces the OSGi complexity dramatically

– But it doesn't help with the JPA boilerplate– All transaction management is still up to the developer– The EntityManagerFactoryBuilder still requires you to track the JDBC Driver

13

Managed JPA

> All of the JPA code thus far has been “unmanaged”– The lifecycle of the persistence unit is managed by the application

> In managed JPA the lifecycle of a JPA resource is managed by a container

– In application-managed JPA the EntityManagerFactory lifecycle is managed so there is one less resource to create and close

– In container-managed JPA the EntityManager lifecycle is also managed, so no resources need to be created or closed

> Managed JPA can automatically integrate with JTA transactions– This reduces JPA boilerplate (no more EntityTransaction)– Plus you can have two phase commit!

14

Managed JPA (2)

> When using container-managed JPA the following code is needed to persist an object:

em.persist(persistableObject);

> Application-managed code is more verbose as the application is responsible for closing the EntityManager

EntityManager em = emf.createEntityManager();try { em.persist(persistableObject);} finally { em.close();}

15

JPA in Apache Aries

> The Apache Aries project develops and maintains OSGi bundles for adding application container functionality to OSGi– Aries aims to drive and support new specifications based on implementation

experience

> The Aries JPA container builds on the JPA service specification– It uses the Meta-Persistence header to identify persistence bundles– It uses the Persistence Provider service– It registers EntityManagerFactory services using the same properties defined

by OSGi

> JTA integration is provided by the JTA service specification

16

How to use application managed JPA in OSGi (1)

> Your existing bundle probably doesn't need to change!– Meta-Persistence works the same way– You must define JTA and non-JTA DataSource in your

persistence unit definition (or suitable drivers)

> When started, there will still be an EntityManagerFactory service registered for every complete persistence unit– This is dependent on the JPA provider being started

> If the persistence client uses an OSGi service lookup it probably doesn't need to change– It can filter on the “org.apache.aries.jpa.container.managed”

property to make sure it gets a managed factory

PersistenceBundle

EMF Service

17

How to use application managed JPA in OSGi (2)

> The client can use the JTA service to manage transactions– This trades one set of code for another (but there are benefits)

> Apache Aries also offers Container Managed Transactions for blueprint– This also relies on the JTA service– Simple configuration allows methods on a bean to run under a transaction

<bean id=”txBean” class=”com.acme.TxBean”> <tx:transaction method=”*” type=”Required”/></bean>

> This can be used in conjunction with dependency injection<bean id=”injectedBean” class=”com.acme.InjectedBean”> <jpa:unit property=”persistence” unitname=”myPU”/></bean>

18

How to use container managed JPA in OSGi

> Similar setup to application managed– In this case you must use injection to get your EntityManager

<bean id=”txBean” class=”com.acme.TxBean”> <tx:transaction method=”*” type=”Required”/> <jpa:context property=”entityManager” unitname=”myPU”/></bean>

> Everything else is handled for you– The IBM WebSphere Feature Pack for OSGi Applications allows you to

use the JEE annotations rather than xml for injection

> We have replaced 30+ lines of boilerplate with 2 lines of xml!

19

Current Limitations of JPA in OSGi

> Many JPA providers use bytecode weaving to manage classes– There is no standard weaving solution in OSGi– Apache Aries offers a plug point for integrators to offer a framework

specific solution but does not offer one itself– The OSGi Feature Pack for WebSphere offers this function

> Many JPA providers can scan the classpath for managed classes– OSGi modularity prevents the JPA provider from finding classes– The Aries JPA plug point also offers an opportunity for integrators

to scan for managed classes– The OSGi Feature Pack for WebSphere offers this too

> The JPA Service specification does not define container behaviour

20

Useful information about JPA in Apache Aries

> The project lives at http://incubator.apache.org/aries/

> There are four bundles in the Aries JPA container– An API/SPI bundle for the integration plug point interfaces– The core JPA container implementation (for application managed JPA)– The JPA blueprint implementation (for the blueprint integration)– The JPA container context implementation (for container managed JPA)

> The blueprint xml namespaces for JPA and transactions are– http://aries.apache.org/xmlns/jpa/v1.0.0– http://aries.apache.org/xmlns/transactions/v1.0.0

Tim Ward http://www.ibm.comIBM timothy.ward@uk.ibm.com

Apache Aries: http://incubator.apache.org/aries/