View source for EclipseLink/Development/OSGi Proof of Concept

{{underconstruction}}

=== @Deprecated ===

There is a new OSGI demo.  Wiki docs are under construction.  For current instructions see:

http://dev.eclipse.org/svnroot/rt/org.eclipse.persistence/trunk/examples/org.eclipse.persistence.example.jpa.rcp.comics/ReadMe.txt

== Tag 0.2 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.
* 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.
* With the above features, it is possible for client code to obtain an EntityManagerFactory three different ways:
*# Using the standard Java Persistence API with configuration behind the scenes using OSGi services and Manifest properties for configuration. See "org.eclipse.persistence.demo.jpa.osgi.spi" for an example.
*# Using the standard Java Persistence API--classloader to use for a given persistence unit passed in a property to createEntityManagerFactory instead of Manifest configuration.  See "org.eclipse.persistence.demo.jpa.osgi.spi.classloader" for an example.
*# Using EclipseLink OSGi specific JPA Persistence Provider requiring no OSGi configuration.  See "org.eclipse.persistence.demo.jpa.osgi.provider" for an example.
* 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.
* Use of bundles (jars) in a Java SE environment or EE environment for JPA.  JAXB usage has not been tried but should not be a problem.

=== Known Not Working ===
* Database platform discovery.  Persistence.xml must define the eclipselink.target-database property.
* SDO is currently not working. 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.  Blaise Doughan is looking into how EclipseLink SDO can make use of a provided classloader to enable it to work in OSGi.

== 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 [http://dev.eclipse.org/viewsvn/index.cgi/org.eclipse.persistence/branches/osgi/?root=Technology_SVN /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 (Tag 0.2), 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)
'''jpa'''
* eclipselink.jpa (org.eclipse.persistence.jpa)
* javax.persistence
'''moxy'''
* eclipselink.moxy (org.eclipse.persistence.moxy)
* javax.xml.bind
'''lib'''
* javax.activation
* javax.ejb
* javax.jms
* javax.mail
* javax.resource
* javax.transaction
* javax.xml.rpc
* javax.xml.stream
* org.apache.ant
* org.apache.derby
* org.eclipse.persistence.antlr
* org.eclipse.persistence.asm

=== Demos ===

If you also want to try out the demos you can check the following out:

'''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
* org.eclipse.persistence.osgi.provider.demo
* org.eclipse.persistence.spi.classloader.demo
* org.eclipse.persistence.spi.demo

== Additional Downloads ==
If you plan on running the demos you'll need to download [http://db.apache.org/derby/derby_downloads.html Apache Derby] and run the Derby Network Server.

== Getting Started ==
=== Demo Setup ===
# Run DERBY_ROOT\bin\startNetworkServer[.bat] to start up the Derby Database server.
# Create a new "OSGi Framework" run configuration
# Press the "Deselect All" button
# Check the box beside "org.eclipse.persistence.comics.model.demo.setup" to add it to the run config.
# Press the "Add Required Bundles" button--notice that all the bundles you need to run the demo setup are added to the run configuration.
# Click on javax.persistence and change its run level to 1.  This will ensure that the JPA initialization code will be run before the JPA clients do.
# 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.
# Press the "Run" button and--hopefully--you'll see some SQL and other logged messages fly by.
# You're now in the OSGi console.  To exit type "exit" at the prompt.

[[Image:OSGiPOCDemoSetupRunConfiguration.jpg]]

== Creating a JPA application bundle using the standard JPA SPI ==

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.