There are two disadvantages with respect to the single bundle approach (apart from
that it’s just ugly). Suppose you would develop deploy several bundles that provide
persistence services, and that these would all contain the OpenJPA jar (2.8 M) and all
of its supporting libraries (another megabyte). Having copies of these jars in each
bundle whould be a waste of space (disk space and memory!) and if you would
like to update one library, you’d have to update all bundles. Of course, it would be
much better if each “component” (whatever that me be) is in its own bundle.

Another issue is that the domain objects (in the code sample the Person
class) are bundled together with the persistence service. This is not ideal, as you can
image that domain objects can be used without persistence. Bundling them together would
require each application that uses domain objects, to have the persistence service
bundle to be installed as well. Having the domain objects in a separate,
independant bundle, results in a more modular configuration.

A domain bundle

We’ll start with the last issue, as this is the simplest one to fix. Starting point is
the sample code we developed last time (download the zip for all sample code).
The test client, a bundle that extends the
Felix command shell with a simple command to call our persistence service, is exactly
the same as last time. However, if you compare the first build file
(build1.xml) of the jpa-sample bundle with the ones from the previous blog
entry, you’ll notice differences with respect to imports of the sample bundle. This is
the result of upgrading to OpenJPA 1.1.0. With this new OpenJPA version, a number of
(obscure) dependencies (oracle, apache.avalon, weblogic) seem to be vanished, and also
commons-logging doesn’t seem to be required anymore, so we could clean up the
<bundle&gt task a bit.

Separating the domain classes is easy: create a bundle that only contains the
net.luminis.sample.jpainosgi.domain package. At the same time, we’ll
remove this package from the existing jpasample bundle (that is now
renamed to jpa-sample-service). This is not
required (OSGi can handle several bundles providing the same package), but we want to
ensure that our new setup works when the domain classes are in the domain bundle only.
However, as the domain classes use the javax.persistence package, this is
not enough: someone must export this package in order to make the domain bundle
resolvable. As this package is in the jpa-sample-service bundle, we’ll add an extra
export there (build2.xml).

If you’d deploy these two bundles in Felix and test it, you’d notice this works. But
it’s not yet perfect: due to the javax.persistence package that is
provided by the jpa-sample-service bundle, our newly created domain bundle still needs
the service bundle. That’s not we wanted, the domain bundle should be completely
independent from the service bundle! Hence, we must move out the
javax.persistence from the service bundle and make it a separate bundle.

Supporting libraries

The OpenJPA distribution comes with an implementation of the
javax.persistence package
(geronimo-jta_1.1_spec-1.1.jar). Turning this library into an OSGi bundle
is not difficult, and can be easily achieved with the Bnd tool (*).
But creating these bundles by hand is not necessary anymore, because the
javax.persistence and javax.transaction libraries that are
shipped with Apache Geronimo since version 2.1, are already OSGi bundles.
If you download the 2.1.2 Geronimo release, you’ll find the libraries in the
geronimo-jetty6-javaee5-2.1.2/repository/org/apache/geronimo/specs
subdirectory.

There are more common libraries that are used by OpenJPA and that can be easily
stripped from the bundle: the most used Apache Commons libraries are nowadays released as OSGi
bundles too. Unfortunately, the ones shipped with OpenJPA are not OSGi ready, but the
newest releases of Commons Collections, Commons Lang and Commons Pool are (see
overview). So you can simply
download these new versions and install them right away in your OSGi framework.

The Postgres JDBC driver is not yet available as OSGi bundle, so i fixed this by hand
(with a little help from Bnd). You can download this bundle, as well as the Bnd
configuration file used to create this bundle, from the
luminis open source server.
This results in a much smaller jpa-sample-service
bundle (build4.xml).

OpenJPA OSGi bundle

The final step, removing the openjar itself from our bundle, is a little bit more
tricky. We start by creating a bundle from the OpenJPA jar file. This time the Bnd
configuration file is less trivial; not only we must provide the (do-not)import
specifications that were previously in the build file (!org.apache.tools.ant;
!org.apache.tools.ant.types;, etc), but also we need to explicitely export the
packages that will be needed by other bundles. This leads to an OSGi enabled version of
the OpenJPA jar (download it here).
Next we remove the openjpa stuff from our jpa-sample-service bundle. Trying to run this
version results in an “Creating EntityManagerFactory failed!” error. What’s going on here?

To understand what’s going on, we must understand how the generic
javax.persistence.Persistence class, finds a specific
EntityManagerFactory (since that class is part of the JPA implementation
you use, in constract to the Persistence class that bootstraps it). The find out which
JPA implementation you’d like the use, the Persistence class searches the classpath for
a provider configuration file in the META-INF/services resource
directory, see href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider">Jar
file specification (actually, it asks the thread-context-classloader to list all
these files). In our old scenario, with the openjpa jar inside the bundle, this worked
well because the openjpa.jar was on the bundle-classpath (and hence, could be loaded by
the bundle classloader, that was set as context-classloader). But now, these service
definitions are in another bundle and it is not possible to load these resources from
outside (it is possible to load resources from another bundle, but not in this way).

We can solve this problem by explicitly telling the Persistence class which persistence
provider we want. This is possible by passing a property:

props.put("javax.persistence.provider", "org.apache.openjpa.persistence.PersistenceProviderImpl");

Hard-coding this is of course bad style, as we would tie our persistence service to one
specific JPA implementation. In production ready software, one would make this configurable.

Now, the Persistence class knows which persistence provider (class) to create. We must
only ensure that this class is visible for the jpa-sample-service bundle: it must
import org.apache.openjpa.persistence and org.apache.openjpa.jdbc.kernel. With this
setup (build5.xml) the bundle can start and create an EntityManagerFactory.

Unfortunately, this does not mean that calling the persistence service succeeds. When
you try, you’ll get a ClassNotFoundException for the Person class. This is caused by
the fact that OpenJPA tries to load the Person class from the same classloader that has loaded
the OpenJPA classes. In this case, that is the bundle classloader of the openjpa.jar
bundle, which of course, cannot find the Person class (it does not import it). In the
previous setup, both the openjpa.jar and the Person class were in the same bundle and
thus loaded via the same (bundle) classloader.

We can solve this by setting the thread context classloader, as OpenJPA tries that
classloader too. The disadvantage of this approach is that we have to add
setContextClassLoader() calls to each and every method in our service
implementation that uses JPA, e.g.

public void list() {
    ClassLoader oldCL = Thread.currentThread().getContextClassLoader();
    Thread.currentThread().setContextClassLoader(this.getClass().getClassLoader());

    EntityManager entityManager = entityManagerFactory.createEntityManager();

    EntityTransaction transaction = entityManager.getTransaction();
    try {
        transaction.begin();
        List resultList = entityManager.createQuery("select p from Person p").getResultList();
        System.out.println("List of all persons in db: ");
        for (Object p: resultList)
            System.out.println(p);
    }
    finally {
        transaction.commit();
        entityManager.close();
    }
    Thread.currentThread().setContextClassLoader(oldCL);
}

Of course, this is not what we want. We want to be able to use a “normal” piece of
(JPA) persistence code, without change, in a service implementation. The classloader
fiddling is an infrastructure aspect, that should be separated from our business
code. A simple solution is to use a proxy object that takes care of the context
classloader, see the sample source code for details.

Setting the context classloader solves the class not found issue, but reveals another
one: OpenJPA now complains that the Person class is not enhanced. This is strange,
because OpenJPA enhance persistent classes on the fly – after all, that is how it
worked in all the previous samples. I tried to track down this issue; it has to do with
a difference between the classloader that is used to enhance the classes and the one
that is used for accessing these classes. I’m not sure yet whether this is an OpenJPA
or an OSGi (or Felix) issue. Anyway, it’s easy to solve by enhancing the classes
beforehand. If you run the enhance task in build6.xml before the
bundle task, it creates a domain bundle with pre-enhanced domain
classes. Deploy this bundle in Felix, and see how it all works fine now!

We finally arrived at the situation with two very small sample bundles, that contain no
infrastructural libraries anymore. All libraries used are now bundles on their own, and
deploying these in an OSGi framework is all what it takes to make it work.

Conclusion

We showed that using OpenJPA in an OSGi context is very easy. An OSGi service
implementation that uses OpenJPA, can be implemented in the same way you would do when
used outside OSGi. Although there is one small difference, the need for setting the thread context
classloader upon each service invocation, this can be easily hidden by using a
proxy. If you want to maximize ease of development, and have no worries about the
overhead caused by using dynamic proxies, you could use a dynamic proxy that
automatically delegates all methods in the interface.

The bottom line is that using OpenJPA within an OSGi context is painless. That makes
OpenJPA a perfect solution for introducing persistency in an OSGi based application.

For our experiments, we take a simple JPA example, consisting of one entity class Person and a Persister class that will either list all the person items in the database, or add a new one. For example, its create method looks like this:

public void create(Person person) {
    EntityManager entityManager = entityManagerFactory.createEntityManager();
    EntityTransaction transaction = entityManager.getTransaction();
    try {
        transaction.begin();
        entityManager.persist(person);
        transaction.commit();
    }
    finally {
        if (transaction.isActive())
            transaction.rollback();
        entityManager.close();
    }
}

Both operations (create & list) are contained in an interface that is published as an OSGi service, which enables code external to our jpa bundle to use this functions.

The first step in our little experiment is of course to create a bundle for these classes. We’ll use the Bnd tool for this, wrapped in the ant task that is available on http://opensource.luminis.net. We’ll start with the naive approach: we create a bundle that only contains our sample classes, add an activator and see what happens. The activator calls the Persister.initJPA() method in its start method, that tries to create the EntityManagerFactory:

private void initJPA() {
    Properties props = new Properties();
    entityManagerFactory = Persistence.createEntityManagerFactory("openjpa", props);
    if (entityManagerFactory == null)
        throw new RuntimeException("Creating EntityManagerFactory failed");
    else
        System.out.println("Init JPA ok.");
}

Of course JPA can not function without its persistence.xml file, which we add in the META-INF directory of our bundle (see build-attempt1.xml).

Installing this bundle in Felix results in one unresolved package: javax.persistence. This is easy to understand: our Person class uses JPA annotations (@Entity, @Id). We'll take the geronimo-jpa_3.0_spec-1.0.jar that comes with openJPA and add this to our bundle (eventually, we would like to make this separate bundles, but let's focus on getting it to work first). To do so, we adapt the build file to include the jar as a resource and set it on the bundle classpath explicitely (see build-attempt2.xml).

Loading this next version of the bundle in Felix, results in an exception: because the EntityManagerFactory is null. Note that there is no openJPA exception that gives us a clue about what is going wrong, but it's likely that is has something to do with the fact that we did not yet deploy any openJPA jars. So we add the openjpa-1.0.2.jar to the bundle and try again. If we try to load this bundle in Felix, it complains about an unresolved org.apache.tools.ant.types package. If we study the Import-Packages header generated by Bnd, we see a long list of missing dependencies, containing the usual suspects like org.apache.commons.lang, but also containing items like

• com.ibm.websphere.jtaextensions
• oracle.sql
• org.apache.tools.ant.taskdefs
• sun.misc
• weblogic.transaction

which will a bit harder to track down. We take the pragmatic approach of adding the packages that (we think) openJPA really needs and ignore the others. In the end, we won't get away with this approach, but for now, it suffices. See the build file build-attempt5.xml for the exact list of ignored packages and the openJPA libaries that are added on the bundle classpath.

Note that the geronimo-jta_1.1_spec-1.1.jar that provides javax.transaction is needed, even though this package is delivered with the JDK and Felix makes it available on the system classpath. The funny thing is, is that the JDK version of this packages includes only a few classes of this package (and its javax.transaction.xa subpackage). This leads to the strange behaviour that the bundle does not load with a ClassNotFoundException, even though the package javax.transaction can be resolved!

Unfortunately, adding all these jars did not resolve the issue of having no EntityManagerFactory. This turns out to be a classloader issue: the openJPA classes are on the bundle classpath, but the JPA bootstrap code (the Persistence class) doesn't know about the bundle classloader. This can be solved by passing the bundle classloader as context classloader:

private void initJPA() {

    ClassLoader oldCL = Thread.currentThread().getContextClassLoader();
    Thread.currentThread().setContextClassLoader(this.getClass().getClassLoader());
    Properties props = new Properties();
    entityManagerFactory = Persistence.createEntityManagerFactory("openjpa", props);
    ...
    Thread.currentThread().setContextClassLoader(oldCL);
}

Note the last line of this method: its considered good practice to switch back to the original context classloader before returning.

Now the initJPA method seems to succeed, it's time for a real test. If you downloaded the source code of this samples, you'll find a seperate bundle (perscmd.jar) that adds an interactive command to the Felix shell, that will talk to our PersonPersistence service. This command bundle works only with Felix (i.e. with the Felix command shell), but you can easily create a similar bundle for other frameworks, e.g. Equinox or Knopflerfish.
Running this command shows that we're not done yet: the jdbc driver class can't be loaded. Adding the jdbc driver jar to the bundle classpath (postgres in our case) solves this last classloader problem and after creating a database and a "person" table, we can finally create persistent Person classes, as the following trace of the Felix interactive shell shows:

-> persistence list
List of all persons in db:
-> persistence create 1 john
-> persistence create 2 mike
-> persistence list
List of all persons in db:
john (1); registered on Mon Mar 24 21:19:53 CET 2008
mike (2); registered on Mon Mar 24 21:20:00 CET 2008
->

The conclusion is that it is fairly simple to use openJPA in an OSGi bundle. Actually, i was quite surprised how easy it turned out to be, given my previous experience with other persistency frameworks. I guess the fact that a library is so easily deployed in a context it was not designed for, tells us something about the quality of the library. And by the way, i got the same impression about quality when browsing through the code, trying to pinpoint the few problems i had to solve.

Conclusion

There are a few things to improve. First, bundling everything in the same jar is a bit of a brute force approach; ideally, we should create one or more separate bundles for the openJPA stuff. I did some work on this already, maybe i'll come back to that later.
Second, we created a sort of a work around for the unresolved imports, which should be solved differently.
However, i think both issues are doable in reasonable time, so for me openJPA is considered a good candidate for adding persistence to OSGi applications.