Jump to: navigation, search

Difference between revisions of "EclipseLink/Examples/OSGi/Equinox Byte Code Weaving"

m (Passing Class Loader)
m
 
(26 intermediate revisions by one other user not shown)
Line 1: Line 1:
=Under Construction=
+
The OSGi support provided by EclipseLink is deprecated and has been replaced by the Gemini JPA project.  See the [[Gemini/JPA/Documentation|Gemini documentation]] for examples.
 
+
= Overview =
+
In EclipseLink 1.1.2 (Galileo) and above, EclipseLink JPA byte code weaving is supported in Equinox OSGi.  Configuration is straight forward and the requirements on your JPA persistence unit bundle are minimal.
+
 
+
== Background ==
+
Byte code weaving support is implemented through two fragments: org.eclipse.persistence.jpa.equinox.weaving and org.eclipse.persistence.jpa.equinox.
+
o.e.p.j.equinox.weaving is a fragment for the system bundle org.eclipse.osgi.  Extending the system bundle is a special case in OSGi and such a fragment is called a ''framework extension''.  This extension make use of the Equinox [[AdaptorHook]] framework to hook into the byte code loading process and perform weaving when necessary.  Configuring a framework extension is done using the standard OSGi ''osgi.framework.extensions'' property.  This property needs to be declared either in your config.ini or on the commandline as:
+
<pre>
+
osgi.framework.extensions=org.eclipse.persistence.jpa.equinox.weaving
+
</pre>
+
 
+
o.e.p.j.equinox is a fragment for the org.eclipse.persistence.jpa bundle that registers byte code weavers for persistence units that require it.  All that is necessary to enable this is to deploy it with your other bundles.
+
 
+
= Setup =
+
NOTE: This example does not address how to develop an EclipseLink OSGi application in Eclipse PDE.  It covers how to configure a runtime environment that supports byte code weaving for EclipseLink JPA.  See [[Developing EclipseLink OSGi in PDE]] to learn how to develop EclipseLink OSGi applications in Eclipse
+
 
+
* Create a root folder for the example, we'll refer to it as HOME.
+
== Required Bundles ==
+
* Download [http://download.eclipse.org/equinox Equinox 3.5] to obtain the following bundles and place them in HOME\plugins.
+
** org.eclipse.equinox.common
+
** org.eclipse.osgi
+
* From the Equinox download page, download the launcher appropriate for your operating system.  The launcher comes in two parts: a bundle and a native platform library.  Copy both the launcher jar and native library folder to HOME\plugins.
+
* From an Eclipse 3.5 install's plugins folder copy the following bundle to HOME\plugins:
+
** org.eclipse.update.configurator
+
* Download the Apache Derby database bundle ''org.apache.derby'' from the [http://download.eclipse.org/tools/orbit/downloads/| Eclipse Orbit download page] and place it in HOME\plugins.  The Orbit bundle does not contain the client driver so we'll use an embedded database in this example.
+
* [http://www.eclipse.org/eclipselink/downloads/index.php| Download EclipseLink 1.1.2] (or above) and place the bundles into HOME\plugins
+
 
+
== Enabling Byte Code Weaving in your Application  ==
+
The following requirements must be met to enable byte code weaving on your Entities:
+
# Provide class loader to Persistence.createEntityManagerFactory
+
# Bundle org.eclipse.persistence.jpa must be required by your bundle
+
# Explicitly indicate you want byte code weaving in your persistence.xml
+
 
+
=== Passing Class Loader ===
+
Access to the classloader that loads your Entities is required by EclipseLink.  In your application you need to pass this classloader as a property to Persistence.createEntityManagerFactory(). Failure to provide the classloader will result in a failure.
+
 
+
<source lang="java">
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
...
+
Map<String,Object> properties = new HashMap<String, Object>();
+
properties.put(PersistenceUnitProperties.CLASSLOADER, this.getClass().getClassLoader());
+
emf = Persistence.createEntityManagerFactory("comics", properties);
+
</source>
+
 
+
=== Require org.eclipse.persistence.jpa ===
+
In the manifest.mf of your application bundle, you need to require the org.eclipse.persistence.jpa bundle.  Note that the minimum version that supports byte code weaving in OSGi is 1.1.2 (Galileo).
+
 
+
<pre>
+
...
+
Require-Bundle: org.eclipse.persistence.jpa;bundle-version="1.1.2"
+
...
+
</pre>
+
 
+
=== Enable Weaving in persistence.xml ===
+
Typically, byte code weaving is automatically enabled by EclipseLink based on what environment it's running in.  For example, in a Java EE5 container byte code weaving is always enabled.  In Equinox, byte code weaving is not automatically enabled.  If you have configured your Equinox runtime target correctly, you can go ahead and indicate that you want byte code weaving to be performed.
+
 
+
<source lang="xml">
+
<property name="eclipselink.weaving" value="true"/>
+
</source>
+
 
+
== Equinox Configuration ==
+
* Create the file config.ini in HOME\configuration with the contents:
+
 
+
<pre>
+
osgi.bundles.defaultStartLevel=6
+
eclipse.ignoreApp=true
+
osgi.noShutdown=true
+
osgi.framework.extensions=org.eclipse.persistence.jpa.equinox.weaving
+
osgi.bundles= \
+
org.eclipse.equinox.common@2:start, \
+
org.eclipse.update.configurator@3:start, \
+
javax.persistence@4:start, \
+
org.eclipse.persistence.jpa@5:start, \
+
org.eclipse.persistence.antlr, \
+
org.eclipse.persistence.asm, \
+
org.eclipse.persistence.core, \
+
org.eclipse.persistence.jpa.equinox, \
+
org.eclipse.persistence.example.equinox.weaving@start, \
+
org.apache.derby
+
</pre>
+

Latest revision as of 12:46, 24 October 2012

The OSGi support provided by EclipseLink is deprecated and has been replaced by the Gemini JPA project. See the Gemini documentation for examples.