This week the EclipseLink team announced the release of EclipseLink 1.0. I've been using EclipseLink on S2AP for a while now; in fact, I used EclipseLink when developing our JPA load-time-weaving support.

We've yet to upgrade our internal usage to 1.0 - our beta9 was tagged just before the announcement - but I wanted to demonstrate how effectively the pairing works in an OSGi environment.

EclipseLink in Petclinic

In the 1.2.0 version of the S2AP Petclinic sample, we released the EclipseLink implementation of the Clinic back-end. The back-end is a drop-in replacement for the JDBC back-end that was previously the only option.

Building Petclinic EclipseLink

To build the EclipseLink version of Petclinic, simply open a terminal window in the Petclinic root directory and run:

This will create the Petclinic EclipseLink PAR file in org.springframework.petclinic.eclipselink/target/artifacts/org.springframework.petclinic.eclipselink.par and will put all the required bundles in org.springframework.petclinic.eclipselink/target/par-provided/bundles/.

Running Petclinic EclipseLink

To run the Petclinic EclipseLink application, copy all the provided bundles to the S2AP repository directory:

And then copy the PAR file to the S2AP pickup directory:

Once that is done, you can start the HSQLDB database needed by the Petclinic application:

Now start the S2AP instance:

When this is complete you should see log messages like this:

Testing Petclinic EclipseLink

To try the application out, simply hit http://localhost:8080/petclinic:

Modularity in Petclinic EclipseLink

The Petclinic EclipseLink application is made up of six bundles:

The domain, web, repository and infrastructure bundles are common across all versions of the application. These bundles have the following roles:

• domain - contains the persistent types such as Pet and Vet
• repository - contains the main repository interface Clinic
• web - contains all the web front-end classes and configuration
• infrastructure - defines the DataSource to connect to HSQLDB and exports this as a service

Note that the web bundle only depends on the domain and repository bundles at the module level. This means that web only needs types from those two bundles. In the case of Clinic which is an interface, the web bundle gets its implementation from OSGi:

Basic JPA Implementation and Configuration

The implementation of the Clinic interface is provided by the repository.jpa bundle. It is worthwhile looking at the implementation and configuration of this bundle in some detail. The EntityManagerClinic class implements Clinic using JPA:

This class depends on a standard JPA EntityManager which is annotated for injection using @PersistenceContext. The transaction configuration is defined using Spring's @Transactional annotation. The configuration for the EntityManagerClinic is contained in module-context.xml:

The EntityManagerClinic needs to be injected with an EntityManager. Spring's JPA support provides the LocalContainerEntityManagerFactoryBean which provides access to a shared EntityManager:

To enable Spring transaction management, the configuration defines a JpaTransactionManager:

The JpaVendorAdapter defines which provider you are using, along with the provider-specific configuration. Rather than define the JpaVendorAdapter in-line, Petclinic uses an OSGi service to get the JpaVendorAdapter from another bundle. This allows for different JPA providers to be added without having to change the core repository.jpa bundle.

Enabling Spring's annotation-driven configuration will allow for the configured EntityManager to be injected into the EntityManagerClinic:

Transactions are enabled using the JpaTransactionManager and annotation-driven configuration:

Notice that the configuration defines the transaction mode as aspectj. In this mode, AspectJ load-time weaving is used to apply the transaction behaviour. This requires that Spring's load-time weaving support be enabled and configured for AspectJ weaving:

The LoadTimeWeaver is also used to support the weaving needed by EclipseLink when it transforms the persistent types. No special configuration is needed to use the S2AP LoadTimeWeaver; this will be added when the application is deployed.

The osgi-context.xml configuration pulls in the necessary services and exports the EntityManagerClinic:

Notice that the JpaVendorAdapter is being referenced as an OSGi service - this allows the repository.jpa.eclipselink bundle to provide the exact JpaVendorAdapter needed to run with EclipseLink.

EclipseLink-specific configuration

The configuration for the JpaVendorAdapter is contained in the repository.jpa.eclipselink bundle:

The jpaVendorAdapter bean is then exported as an OSGi service:

Import Scopes

To enable the Clinic implementation to be switched without having to make changes to the four core bundles, it is important that any changes are contained within the implementation bundles only. Unfortunately, this is not possible in standard OSGi.

When EclipseLink weaves a type, it adds dependencies on its own types to that type. For instance, weaving Vet will cause Vet and thus the domain bundle to depend on EclipseLink. One way of solving this is simply to add the appropriate Import-Package or Import-Bundle statements to the domain bundle. This is undesirable because it breaks the modularity - the domain bundle shouldn't care about how it is persisted.

This problem exists wherever bytecode transformation is used, and to a lesser degree where runtime class generation is used. For example, when using Hibernate, CGLIB is used to generate subclasses of persistent types. For the most part this is fine, except when some other code starts to reflect on objects of this dynamically generated type. This is quite common in web code, where reflection is used for data binding - all of a sudden the web bundle finds it has a dependency on Hibernate!

To solve this, S2AP supports the notion of Import Scopes. When using Import-Bundle inside an application, you can define that the scope of the import is the application. This will cause the import to be added to all the other modules in the application dynamically. This allows you to get the dependencies you need to make your application run, but without having to make changes to your application that might limit its flexibility.

Configuring Import Scope

The repository.jpa bundle has no dependency on EclipseLink:

The repository.jpa.eclipselink bundle introduces the EclipseLink dependency and defines that all the application modules should see EclipseLink:

Summary

Using EclipseLink and JPA in the SpringSource Application Platform requires very little extra effort on your part. The Import Scope feature allows you to keep your non-EclipseLink modules completely isolated from your usage of EclipseLink.