Difference between revisions of "EclipseLink/Development/OSGi Proof of Concept"

Revision as of 14:02, 25 January 2008

Template:Underconstruction

Status

Working Features

• Bundles containing simple JPA applications are running. Not all JPA mapping types and features have been tried, just those used in the demos.
• Ability for client code to obtain an EntityManagerFactory using the standard Java Persistence API.
• javax.persistence.Persistence has been extended with support for a pluggable provider resolver. A service approach has been taken for providers (like EclipseLink) to publish their availability.
• Mechanism for bundles containing persistence units to register with EclipseLink JPA. The current implementation is probably better implemented using services and will likely change.
• JAXB 2.0 demos are running. A JAXBContext must be created using the JAXB Spec newInstance(String, ClassLoader) method to provide MOXy with the class loader that has visibility to the domain model classes.

Known Not Working

• Database platform discovery. Persistence.xml must define the eclipselink.target-database property.
• SDO is currently not working and it's unlikely to ever be available in separate bundle due to the implementation of the SDO specification classes. Unlike JAXB, SDO does not allow for the provision of a class loader and so must be packaged in the same bundle as the client code.
• Use of bundle jars in Java SE environment. A few resources are not in the right place to be found when the bundles are used as jars. This will be addressed very soon.

Where to get the EclipseLink OSGi Proof of Concept

The POC is being developed in a branch of the EclipseLink Subversion repository named "osgi". This branch started with the EclipseLink 1.0M3 build. To see what changes have been made you can diff with the 1.0M3 tag. The EclipseLink SVN repository is under technology at /svnroot/technology/org.eclipse.persistence/branches/osgi. Under "osgi" there is a standard SVN repository layout so that we can tag the POC at different points. To get a stable build you can check out the most recent tag.

Although the osgi branch contains a complete copy of EclipseLink 1.0M3, only a few of the projects are involved with this POC. They're listed below.

POC Projects/Bundles

To try the POC, you need to checkout the projects below. Each folder contains a project. The names of the projects that will appear in your workspace, if different than the folder name, are in parenthesis. The folder names weren't changed for fear of complicating the Subversion diff process. If you're using Subversive in Eclipse you right click on each of the folders and choose "Check Out" from the popup menu.

foundation

• eclipselink.core (org.eclipse.persistence.foundation)
• eclipselink.core.lib (org.eclipse.persistence.foundation.lib)

jpa

• eclipselink.jpa (org.eclipse.persistence.jpa)
• javax.persistence

moxy

• eclipselink.moxy (org.eclipse.persistence.moxy)
• javax.xml.bind

demo

• org.eclipse.persistence.comics.colocated.orm.xml.demo
• org.eclipse.persistence.comics.model.annotated
• org.eclipse.persistence.comics.model.annotated.colocated.demo
• org.eclipse.persistence.comics.model.annotated.demo
• org.eclipse.persistence.comics.model.demo.setup
• org.eclipse.persistence.comics.model.orm.xml.demo
• org.eclipse.persistence.comics.model.unannotated
• org.eclipse.persistence.moxy.demo

lib

• org.apache.derby

Additional Downloads

If you plan on running the demos you'll need to download Apache Derby. The client code available as a bundle in org.apache.derby is release 10.1.2.1 which was used because it was already available as a bundle from the Corona project. This was used with a 10.3.2.0 network server successfully.

Getting Started

Demo Setup

1. Run DERBY_ROOT\bin\startNetworkServer[.bat] to start up the Derby Database server.
2. Create a new "OSGi Framework" run configuration
3. Press the "Deselect All" button
4. Check the box beside "org.eclipse.persistence.comics.model.demo.setup" to add it to the run config.
5. Press the "Add Required Bundles" button--notice that all the bundles you need to run the demo setup are added to the run configuration.
6. Click on javax.persistence.jpa and change its run level to 1. This will ensure that the JPA initialization code will be run before the JPA clients do.
7. Click on org.eclipse.persistence.jpa and change its run level to 2. This will ensure that the JPA Provider initialization code will be run before the JPA clients do and after the javax.persitence bundle is listening for providers.
8. Press the "Run" button and--hopefully--you'll see some SQL and other logged messages fly by.
9. You're now in the OSGi console. To exit type "exit" at the prompt.

Creating a bundle with JPA

To write a bundle that uses EclipseLink JPA you need to build a bundle that requires (directly or indirectly) org.eclipse.persistence.jpa and the bundle containing your JDBC driver (e.g., org.apache.derby). If your code is compiling in PDE, then all you need to do to make the code run with the POC is to define an Activator, configure your MANIFEST.MF to use it, and add a property to your MANIFEST.MF to indicate the persistence units your bundle provides.

Your Activator class must implement org.osgi.framework.BundleActivator. To see this class your bundle must require org.eclipse.osgi (this is the easiest way to do this but this instruction will be updated once I figure out how to import this class and not hardwire the dependency on an Equinox specific bundle--Shaun). You have to implement the start and stop methods but they can be empty. Once you have this class you can use the PDE manifest editor to set it as your bundle activator or you can edit the source to include something like: Bundle-Activator: my.Activator.

Finally, you will need to add the JPA-PersistenceUnits declaration to your manifest, e.g. JPA-PersistenceUnits: myPersistenceUnit. This declares that your bundle contains the specified persistence unit and EclipseLink will use your bundle class loader to locate persistence.xml, orm.xml, and your domain model classes. JPA-PersistenceUnits: can be followed by a comma separated list if you have more than one persistence unit.

At this point you have everything you need but a way to run any application code. In a real application you probably have a UI (as in an RCP app) or are listening on a port to process requests. In the demos the Activator.start method is used to run some code. You can use this strategy to get started.