Jump to: navigation, search

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

m (Running Equinox)
m
 
(12 intermediate revisions by one other user not shown)
Line 1: Line 1:
= Overview =
+
The OSGi support provided by EclipseLink is deprecated and has been replaced by the Gemini JPA projectSee the [[Gemini/JPA/Documentation|Gemini documentation]] for examples.
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.osgiExtending 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 =
+
 
+
First create a root folder for the example, we'll refer to it as HOME.
+
 
+
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 [[EclipseLink/Examples/OSGi/Developing with EclipseLink OSGi in PDE|Developing with EclipseLink OSGi in PDE]] to learn how to configure PDE and develop OSGi applications in Eclipse.
+
 
+
== Required Bundles ==
+
* Download [http://download.eclipse.org/equinox Equinox 3.5] to obtain the following bundles or copy them from an Eclipse 3.5 IDE install's plugins folder and place them in HOME\plugins:
+
** org.eclipse.equinox.common
+
** org.eclipse.osgi
+
* From the [http://download.eclipse.org/equinox Equinox download page] download the launcher appropriate for your operating system. The launcher comes in three parts: a native platform executable, a native platform library (packaged as an exploded bundle), and launcher jar.  Copy both the launcher jar and native library folder to HOME\plugins.  Copy the executable to HOME.
+
:For example, for Win 32 you'll need to extract the following from the launcher zip:
+
<pre>
+
features\org.eclipse.equinox.executable_<version>\bin\win32\win32\x86\launcher.exe
+
plugins\org.eclipse.equinox.launcher.win32.win32.x86_<version>
+
plugins\org.eclipse.equinox.launcher_<version>.jar
+
</pre>
+
* From an Eclipse 3.5 IDE install's plugins folder copy the following bundle to HOME\plugins:
+
** org.eclipse.update.configurator
+
* [http://www.eclipse.org/eclipselink/downloads/index.php Download EclipseLink 1.1.2] (or above) and place the bundles into HOME\plugins
+
* Place your JDBC driver bundle in HOME\plugins.
+
:For example, you can download the Apache Derby database bundle ''org.apache.derby'' from the [http://download.eclipse.org/tools/orbit/downloads Eclipse Orbit download page].  The Orbit bundle does not contain the client driver so you would be limited to an embedded database.  Note that when using an embedded database only one process can have the database open at a time.  Here's an example of the EclipseLink login and config settings for an embedded Derby database:
+
 
+
<source lang="xml">
+
<property name="eclipselink.target-database" value="Derby"/>
+
<property name="eclipselink.jdbc.driver" value="org.apache.derby.jdbc.EmbeddedDriver"/>
+
<property name="eclipselink.jdbc.url" value="jdbc:derby:comics;create=true"/>
+
<!-- Setting read and write pool mins to 1 will reduce the initial number of connections. -->
+
<property name="eclipselink.jdbc.read-connections.min" value="1"/>
+
<property name="eclipselink.jdbc.write-connections.min" value="1"/>
+
</source>
+
 
+
== 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
+
# The org.eclipse.persistence.jpa bundle 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 ==
+
When running Equinox with a launcher you define your configuration in a config.ini file which must be placed in HOME\configuration.  Here are the features of note in an example config.ini below:
+
# osgi.bundles.defaultStartLevel is set to 6 so that all the bundles that should be started will be started in an unambiguous order.
+
# osgi.framework.extensions identifies the framework extension org.eclipse.persistence.jpa.equinox.weaving.  This is critical for byte code weaving.
+
# org.eclipse.equinox.common and org.eclipse.update.configurator are started as per the instructions in the [http://www.eclipse.org/equinox/documents/quickstart.php Equinox Quickstart].
+
# javax.persistence is started before org.eclipse.persistence.jpa so that it can start up a service tracker to listen for JPA provider services.
+
# org.eclipse.persistence.jpa is started before user bundles so that it may register itself as a JPA persistence provider.
+
# my.example.jpa.bundle (or whatever you call your JPA bundle) is auto-started.
+
# The JDBC driver bundle (e.g., org.apache.derby) is deployed but started.  Check the documentation of your driver to see if it must be started
+
 
+
<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, \
+
my.example.jpa.bundle@start, \
+
org.apache.derby
+
</pre>
+
 
+
== Running Equinox ==
+
With the required bundles in the HOME\plugins folder and config.ini in the HOME\configuration folder you're ready to start your application.  On Windows, you can start Equinox by using running the native "launcher.exe" program from the HOME folder.  During development it's recommended you run with the "-clean" option to clear caches between runs.  The "-console" option can be used to interact with Equinox.  This is especially useful when things aren't working as expected.
+
 
+
<pre>
+
> launcher -clean -console
+
</pre>
+
 
+
If launched with -console, you can examine the state of your bundles using the ''ss'' command.  You should see something like:
+
 
+
<pre>
+
osgi> ss
+
 
+
Framework is launched.
+
 
+
id      State      Bundle
+
0      ACTIVE      org.eclipse.osgi_3.5.0.v20090513
+
                    Fragments=1
+
1      RESOLVED    org.eclipse.persistence.jpa.equinox.weaving_1.1.2.v20090519-r4244
+
                    Master=0
+
2      ACTIVE      org.eclipse.equinox.common_3.5.0.v20090513
+
3      ACTIVE      javax.persistence_1.99.0
+
4      ACTIVE      org.eclipse.persistence.jpa_1.1.2.v20090519-r4244
+
                    Fragments=8
+
5      RESOLVED    org.eclipse.persistence.antlr_1.1.2.v20090519-r4244
+
6      RESOLVED    org.eclipse.persistence.asm_1.1.2.v20090519-r4244
+
7      RESOLVED    org.eclipse.persistence.core_1.1.2.v20090519-r4244
+
8      RESOLVED    org.eclipse.persistence.jpa.equinox_1.1.2.v20090519-r4244
+
                    Master=4
+
9      ACTIVE      my.example.jpa.bundle_1.0.0
+
10      RESOLVED    org.apache.derby_10.1.2.1_v200803061811
+
 
+
osgi>
+
</pre>
+
 
+
You can see that that the fragment org.eclipse.persistence.jpa.equinox.weaving (1) has been successfully attached to the org.eclipse.osg (1) bundle.  You can also see that the fragment org.eclipse.persistence.jpa.equinox (8) has been attached to it's master org.eclipse.persistence.jpa (4).
+
 
+
== Confirming Byte Code Weaving is Working ==
+
You can test to see if byte code weaving was successful by checking to see if your entities implement the EclipseLink ''PersistenceWeaved'' interface.
+
 
+
<source lang="java">
+
import org.eclipse.persistence.internal.helper.Helper;
+
import org.eclipse.persistence.internal.weaving.PersistenceWeaved;
+
...
+
if (Helper.classImplementsInterface(MyEntity.class, PersistenceWeaved.class)) {
+
  // MyEntityEntity successfully woven!
+
  ...
+
</source>
+

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.