Purpose
The goal of this article is to show how to integrate EasyBeans/OSGi into the
Eclipse platform.
First, it explains how to run EasyBeans/OSGi server on the Equinox OSGi platform provided with Eclipse.
The second part explains, through a working example, how to develop eclipse plugins and
RCP application which use EasyBeans/OSGi.
Requirements
This tutorial requires that you download the following packages :
- Eclipse platform : Lastest stable version is recommended, currently 3.2.1.
- EasyBeans/OSGi : The EasyBeans/OSGi assembly (currently supports EasyBeans 1.0-M3).
To write this article, the Eclipse Platform Binary package has been used. It will work exactly the same with the IDE package. Nevertheless, it is a good practice to separate the test platform from your development environment.
EasyBeans/OSGi installation on Eclipse
Eclipse installation
Eclipse packages are delivered as ready-to-use archive files. Simply unpack the selected archive into the directory you wish to use for installation.
EasyBeans/OSGi bundles installation
Unpack the downloaded EasyBeans/OSGi assembly into a temp directory. The archive will be expanded as the following structure:
README
build.xml
bundles/
easybeans-entity.jar
easybeans-mdb.jar
easybeans-sfsb.jar
easybeans-slsb.jar
easybeans.jar
ow_easybeans_agent.jar
ow_ezbcomponent_osgi_carol.jar
ow_ezbcomponent_osgi_hsqldb.jar
ow_ezbcomponent_osgi_jdbcpool.jar
ow_ezbcomponent_osgi_joram.jar
ow_ezbcomponent_osgi_jotm.jar
conf/
config.properties
configuration/
config.ini
lib/
ow_easybeans_osgi_client_rt.jar
repository.xml
To deploy EasyBeans/OSGi package on Eclipse you simply need to copy jar files from
bundles/ directory into the
plugins/ directory of your Eclipse platform installation. Not all the files are required as the EasyBeans/OSGi packages include sample bundles. You at least need to copy :
easybeans.jar ow_easybeans_agent.jar ow_ezbcomponent_osgi_carol.jar ow_ezbcomponent_osgi_hsqldb.jar ow_ezbcomponent_osgi_jdbcpool.jar ow_ezbcomponent_osgi_joram.jar ow_ezbcomponent_osgi_jotm.jar
There's currently an
issue opened which concerns the bundle files naming (related to an
Eclipse/Equinox bug in 3.2 Stream). In order to work correctly with Eclipse OSGi implementation, you need to rename the files once they have been copied in
plugins/ directory. Follow the following table to rename the bundle files.
| Original file name | Destination file name |
|---|
easybeans.jar | org.objectweb.easybeans_0.1.0.jar |
ow_easybeans_agent.jar | org.objectweb.easybeans.agent_0.1.0.jar |
ow_ezbcomponent_osgi_carol.jar | org.objectweb.easybeans.carol_0.1.0.jar |
ow_ezbcomponent_osgi_hsqldb.jar | org.objectweb.easybeans.hsqldb_0.1.0.jar |
ow_ezbcomponent_osgi_jdbcpool.jar | org.objectweb.easybeans.jdbcpool_0.1.0.jar |
ow_ezbcomponent_osgi_joram.jar | org.objectweb.easybeans.joram_0.1.0.jar |
ow_ezbcomponent_osgi_jotm.jar | org.objectweb.easybeans.jotm_0.1.0.jar |
Eclipse configuration
Open
configuration/config.ini from your Eclipse platform installation.
Add the following configuration somewhere in the file :
org.osgi.framework.system.packages=org.osgi.framework; version=1.3.0, \
javax.accessibility; \
javax.activity; \
javax.imageio; \
javax.imageio.event; \
javax.imageio.metadata; \
javax.imageio.plugins.bmp; \
javax.imageio.plugins.jpeg; \
javax.imageio.spi; \
javax.imageio.stream; \
javax.management; \
javax.management.loading; \
javax.management.modelmbean; \
javax.management.monitor; \
javax.management.openmbean; \
javax.management.relation; \
javax.management.remote; \
javax.management.remote.rmi; \
javax.management.timer; \
javax.naming; \
javax.naming.directory; \
javax.naming.event; \
javax.naming.ldap; \
javax.naming.spi; \
javax.print; \
javax.print.attribute; \
javax.print.attribute.standard; \
javax.print.event; \
javax.rmi; \
javax.rmi.CORBA; \
javax.rmi.ssl; \
javax.security.auth; \
javax.security.auth.callback; \
javax.security.auth.kerberos; \
javax.security.auth.login; \
javax.security.auth.spi; \
javax.security.auth.x500; \
javax.security.sasl; \
javax.sound.midi; \
javax.sound.midi.spi; \
javax.sound.sampled; \
javax.sound.sampled.spi; \
javax.sql; \
javax.sql.rowset; \
javax.sql.rowset.serial; \
javax.sql.rowset.spi; \
javax.swing; \
javax.swing.border; \
javax.swing.colorchooser; \
javax.swing.event; \
javax.swing.filechooser; \
javax.swing.plaf; \
javax.swing.plaf.basic; \
javax.swing.plaf.metal; \
javax.swing.plaf.multi; \
javax.swing.plaf.synth; \
javax.swing.table; \
javax.swing.text; \
javax.swing.text.html; \
javax.swing.text.html.parser; \
javax.swing.text.rtf; \
javax.swing.tree; \
javax.swing.undo; \
javax.transaction; \
javax.transaction.xa; \
javax.xml; \
javax.xml.datatype; \
javax.xml.namespace; \
javax.xml.parsers; \
javax.xml.transform; \
javax.xml.transform.dom; \
javax.xml.transform.sax; \
javax.xml.transform.stream; \
javax.xml.validation; \
javax.xml.xpath; \
org.ietf.jgss; \
org.omg.CORBA; \
org.omg.CORBA_2_3; \
org.omg.CORBA_2_3.portable; \
org.omg.CORBA.DynAnyPackage; \
org.omg.CORBA.ORBPackage; \
org.omg.CORBA.portable; \
org.omg.CORBA.TypeCodePackage; \
org.omg.CosNaming; \
org.omg.CosNaming.NamingContextExtPackage; \
org.omg.CosNaming.NamingContextPackage; \
org.omg.Dynamic; \
org.omg.DynamicAny; \
org.omg.DynamicAny.DynAnyFactoryPackage; \
org.omg.DynamicAny.DynAnyPackage; \
org.omg.IOP; \
org.omg.IOP.CodecFactoryPackage; \
org.omg.IOP.CodecPackage; \
org.omg.Messaging; \
org.omg.PortableInterceptor; \
org.omg.PortableInterceptor.ORBInitInfoPackage; \
org.omg.PortableServer; \
org.omg.PortableServer.CurrentPackage; \
org.omg.PortableServer.POAManagerPackage; \
org.omg.PortableServer.POAPackage; \
org.omg.PortableServer.portable; \
org.omg.PortableServer.ServantLocatorPackage; \
org.omg.SendingContext; \
org.omg.stub.java.rmi; \
org.omg.stub.javax.management.remote.rmi; \
org.w3c.dom; \
org.w3c.dom.bootstrap; \
org.w3c.dom.css; \
org.w3c.dom.events; \
org.w3c.dom.html; \
org.w3c.dom.ls; \
org.w3c.dom.ranges; \
org.w3c.dom.stylesheets; \
org.w3c.dom.traversal; \
org.w3c.dom.views; \
org.xml.sax; \
org.xml.sax.ext; \
org.xml.sax.helpers; \
version="1.5.0"
configuration/config.ini provided in the EasyBeans/OSGi assembly.Look for the
osgi.bundle property and change it to:
osgi.bundles=org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start,
org.eclipse.core.runtime@start,org.objectweb.easybeans.agent@start
This will tell eclipe to start
org.objectweb.easybeans.agent on startup.
Save the file and exit.
Tests
Now, run eclipse. The best way to see if everything works fine, you can run Eclipse with
-consoleLog argument to see the output on the console. You should see something like that :
$ ./eclipse -consoleLog
Starting : org.objectweb.easybeans.carol Id:update@plugins/org.objectweb.easybeans.carol_0.1.0.jar [83]
17/11/06 14:43:51 (I) TraceCarol.infoCarol : Name service for jrmp is started on port 1099
Starting : org.objectweb.easybeans.jotm Id:update@plugins/org.objectweb.easybeans.jotm_0.1.0.jar [88]
17/11/06 14:43:52 (I) Current.<init> : JOTM 2.0.11
17/11/06 14:43:52 (I) JOTMComponent.start : Register javax.transaction.UserTransaction as transaction manager object
Starting : org.objectweb.easybeans Id:update@plugins/org.objectweb.easybeans_0.1.0.jar [89]
17/11/06 14:43:52 (I) ComponentManager.startComponents : [ Component(s) started : ]
17/11/06 14:43:52 (I) JMXRemoteHelper.init : Creating JMXRemote connector with URl 'service:jmx:rmi:///jndi/rmi://localhost:1099/EasyBeansConnector'
17/11/06 14:43:52 (I) Embedded.start : Demarrage effectue en '183' ms.
17/11/06 14:43:52 (I) Embedded.start : '0' conteneurs ont ete crees.
17/11/06 14:43:52 (I) Embedded.start : En attente de requetes…
Starting : org.objectweb.easybeans.joram Id:update@plugins/org.objectweb.easybeans.joram_0.1.0.jar [87]
17/11/06 14:43:53 (I) JoramComponent.start : Joram version '4.3.20' started on localhost:16010.
Starting : org.objectweb.easybeans.hsqldb Id:update@plugins/org.objectweb.easybeans.hsqldb_0.1.0.jar [85]
17/11/06 14:43:53 (I) HSQLDBComponent.start : Starting 'HSQLDB server' '1.8.0' on port '9001'
17/11/06 14:43:53 (I) HSQLDBComponent.start : HSQLDB server started with URL jdbc:hsqldb:hsql://localhost:9001/easybeans_db
Starting : org.objectweb.easybeans.jdbcpool Id:update@plugins/org.objectweb.easybeans.jdbcpool_0.1.0.jar [86]
17/11/06 14:43:53 (I) JDBCPoolComponent.start : DS 'jdbc_1', URL 'jdbc:hsqldb:hsql://localhost:9001/easybeans_db', Driver = 'org.hsqldb.jdbcDriver'.
This means that EasyBeans/OSGi agent has been started and is ready to work.
In parallel, other bundles are started, so you should see Eclipse workbench appearing on your screen.
Deploying samples
The setup described previously allowed to start EasyBeans/OSGi agent on Eclipse startup. If you wish to start an OSGi EjbJar bundle automatically, you need to modify
configuration/config.ini to change the value for
osgi.bundles.
The following example shows how to start Stateless beans OSGi sample on Eclipse startup :
osgi.bundles=org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start,
org.eclipse.core.runtime@start,org.objectweb.easybeans.agent@start,
org.objectweb.easybeans.examples.stateless@start
Now, if you start again Eclipse with console output, you will see the following trace:
$ ./eclipse -consoleLog
Starting : org.objectweb.easybeans.carol Id:update@plugins/org.objectweb.easybeans.carol_0.1.0.jar [83]
17/11/06 14:58:32 (I) TraceCarol.infoCarol : Name service for jrmp is started on port 1099
Starting : org.objectweb.easybeans.jotm Id:update@plugins/org.objectweb.easybeans.jotm_0.1.0.jar [88]
17/11/06 14:58:33 (I) Current.<init> : JOTM 2.0.11
17/11/06 14:58:33 (I) JOTMComponent.start : Register javax.transaction.UserTransaction as transaction manager object
Starting : org.objectweb.easybeans Id:update@plugins/org.objectweb.easybeans_0.1.0.jar [89]
17/11/06 14:58:33 (I) ComponentManager.startComponents : [ Component(s) started : ]
17/11/06 14:58:33 (I) JMXRemoteHelper.init : Creating JMXRemote connector with URl 'service:jmx:rmi:///jndi/rmi://localhost:1099/EasyBeansConnector'
17/11/06 14:58:33 (I) Embedded.start : Demarrage effectu? en '169' ms.
17/11/06 14:58:33 (I) Embedded.start : '0' conteneurs ont ete crees.
17/11/06 14:58:33 (I) Embedded.start : En attente de requetes…
Starting : org.objectweb.easybeans.joram Id:update@plugins/org.objectweb.easybeans.joram_0.1.0.jar [87]
17/11/06 14:58:34 (I) JoramComponent.start : Joram version '4.3.20' started on localhost:16010.
Starting : org.objectweb.easybeans.hsqldb Id:update@plugins/org.objectweb.easybeans.hsqldb_0.1.0.jar [85]
17/11/06 14:58:34 (I) HSQLDBComponent.start : Starting 'HSQLDB server' '1.8.0' on port '9001'
17/11/06 14:58:34 (I) HSQLDBComponent.start : HSQLDB server started with URL jdbc:hsqldb:hsql://localhost:9001/easybeans_db
Starting : org.objectweb.easybeans.jdbcpool Id:update@plugins/org.objectweb.easybeans.jdbcpool_0.1.0.jar [86]
17/11/06 14:58:34 (I) JDBCPoolComponent.start : DS 'jdbc_1', URL 'jdbc:hsqldb:hsql://localhost:9001/easybeans_db', Driver = 'org.hsqldb.jdbcDriver'.
17/11/06 14:58:34 (I) JContainer3.start : Analyze elapsed during : 70 ms
17/11/06 14:58:34 (I) JContainer3.start : Enhancement elapsed during : 60 ms
17/11/06 14:58:34 (I) JContainer3.start : Container started in : 181 ms
EasyBeans/OSGi agent is started and the Stateless bean sample container is deployed automatically at startup.
RCP Working example
This part concentrates on running the EasyBeans/OSGi bundle in an Eclipse RCP application.
Introduction
Eclipse RCP platform allows Java applications developers to befenit from the power of the Eclipse environnment in the building of client applications.
This platform makes available all the JFace and SWT graphical libraries as well as Eclipse core components.
More concretely, a RCP application is composed of the Eclipse platform on which run on or more plugins. An RCP application can also include others plugins which conform to the OSGi specifications. This is the case of EasyBeans/OSGi bundle. It is so possible to create an RCP application which embed an EJB3 container using the EasyBeans/OSGi bundle.
The following sections will present the different steps involved to create such an application , through a real example :
Escape-K.
Escape-K
Presentation
Escape-K is an open-source project whose goal is to provide a reliable
CMDB platform. It is made of a server part which consists of EJB 3.0 beans, and a client part made with Eclipse RCP platform.
More informations are available directly on
Escape-K's website.
Why using the EasyBeans/OSGi bundle ?
To be able to run Escape-K, users must have J2EE skills. The reason of that is because Escape-K server component must be deployed on an J2EE application server, which was properly configured to run an EJB3 container and also access a datasource.
The needed skills to setup that infrastructure may currently discourage users from trying Escape-K. Therefore, it has been decided to package a stand alone version of Escape-K which provides both server and client part.
This is where EasyBeans and Eclipse met on this project ...
The main idea to package Escape-K server and client parts is to include an EJB3 embbedable container inside the client software. When the user runs the client application it automatically starts the packaged EJB3 container. Server calls from the client are made onto this container. The EJB3 container also includes a database engine, like HSQL, in order to store user data.
This is exactly what EasyBeans/OSGi bundle does, so providing a stand alone version of Escape-K should be as simple as deploying EasyBeans/OSGi bundle inside Escape-K RCP application.
EasyBeans/OSGi integration with Escape-K steps
Test platform setup
As shown in the first part of this article, it is always a good idea to separate Eclipse IDE from the test platform. Therefore, the test platform used for Escape-K development is based on Eclipse binary platform deployed in a separate directory.
Once the Eclipse platform package has been installed in the target directory, EasyBeans/OSGi bundle files have been copied in the
plugins/ directory. The
config.ini file has been left unchanged.
Once the test platform has been, Eclipse has been setup to refer to this platform when running developed plugins. This option is setup through Eclipse preferences in Plug-in Development->Target platform.
As shown in the following screenshot, the location has been changed to refer to the test platform.
The test platform is then ready.
Plug-ins setup.
Escape-K client application is composed of several Eclipse plugins. One of them ,
org.escapek.server, contains all the classes of the server part. Nevertheless, it is needed on the client side because is requires tools classes and interfaces to access the server components.
org.escapek.server plugin needs to be setup because is requires some dependecies from
org.objectweb.easybeans bundle. Therefore, the following directive was added to
MANIFEST.MF file:
Require-Bundle: org.eclipse.core.runtime,
org.objectweb.easybeans,
org.objectweb.easybeans.carol,
org.objectweb.easybeans.joram,
org.objectweb.easybeans.jotm
Server plugin deployment
Because of current limitation is EasyBeans/OSGi version, it is not possible to deploy a EJB3 bundle which exists as a project directory. The problem is that when running a RCP application, Eclipse
runs the platform and references directly the binary folder of the project folders. This is not compatible with EasyBeans/OSGI; the
org.escapek.server plugin has to be deployed on the test platform besides the EasyBeans/OSGi bundle , as a jar file. Therefore, some ant rules were created to compile
org.escapek.server and deploy it on the test platform. These rules can be found in this
build.xml file.
Run configuration setup
Last but not least, a specific Eclipse run configuration needed to be created.
Mostly the plugins configuration needed to be changed so that :
- org.escapek.server is removed from the workspace plugin list
- org.escapek.server is added from the target platform list
- org.objectweb.easybeans.* plugins are launched.
This tells Eclipse to take org.escapek.server plugin from the plugins/ directory of the test platform where it has been deployed instead of from the workspace plugins. This configuration corresponds to the following screenshots:
Conclusion
Escape-K stand alone version was correctly built by following the previous procedure.
It still needs more testing and improvments so it can be used for production.
Project
