Difference between revisions of "Equinox Integration"

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.
m (Basics and JBoss Setup)
(Basics and JBoss Setup)
Line 75: Line 75:
 
** adempiere/adempiere/Adempiere/jboss will then contain a jboss ready to run
 
** adempiere/adempiere/Adempiere/jboss will then contain a jboss ready to run
 
* The Code is in this branch: [http://adempiere.svn.sourceforge.net/viewvc/adempiere/branches/osgi/ '''/branches/osgi/''']
 
* The Code is in this branch: [http://adempiere.svn.sourceforge.net/viewvc/adempiere/branches/osgi/ '''/branches/osgi/''']
*** The ZIP archive consists of the above mentioned 4 eclipse projects - unpack it and import the projects
+
** There are several projects to be seperately checked out aside adempiereTrunk
 
* Check the following libs at [http://adempiere.svn.sourceforge.net/viewvc/adempiere/branches/osgi/Adempiere-patch/lib/ '''/branches/osgi/Adempiere-patch/lib/'''] are in your '''Adempiere-patch/lib''':
 
* Check the following libs at [http://adempiere.svn.sourceforge.net/viewvc/adempiere/branches/osgi/Adempiere-patch/lib/ '''/branches/osgi/Adempiere-patch/lib/'''] are in your '''Adempiere-patch/lib''':
 
** org.eclipse.core.contenttype_3.3.0.v20080604-1400.jar
 
** org.eclipse.core.contenttype_3.3.0.v20080604-1400.jar

Revision as of 00:29, 12 May 2009

Eclipse Equinox Plugins in ADempiere

Eclipse Equinox (http://www.eclipse.org/equinox) is an implementation of OSGi R4. Moreover, it provides applications with a plugin mechanism based on extension points and extensions satisfying them.

Integration with ADempiere is now underway under Joerg Viola.

Currently, an alpha demo is available. The vision is to integrate it into Adempiere core an have every further extension be delivered as a plugin.

Technical documentation

The integration consists of four components, implemented each in its own project in an eclipse environment.

Adempiere patch

  • This patch currently is very simple. It consists of
    • The interface IExtension, a factory for IExtensions called Extension and two implementations:
      • The DefaultExtension contains code extracted from ADempiere core classes.
      • Equinox contains code to delegate the functionality to equinox plugins.
      • Which extension is used, depends on a prefix of e.g. the given classname: osgi://formClassName would use Equinox whereas formClassName would use the DefaultExtension and thus provide a clean fallback
    • Patched core classes, namely:
    • class org.compiere.Adempiere: Start all extensions
    • class org.compiere.apps.form.FormFrame: Form class loading
    • class org.adempiere.util.ProcessUtil: Process class loading
    • class org.compiere.model-GridTab: Callout class loading
    • The Equinox Extension starts the Equinox container
      • It does so in a seperate thread, because the platform modifies the context classloader
      • It fires up an OSGi console on port 1234, so that you may connect to it via telnet and see whats going on
      • It then asks for the so-called "host service", an OSGi-Service gatewaying requests from the patched adempiere core into equinox
    • A lib-folder that must be copied to the runtime classpath
      • In fact, I don't like the way, libraries are re-packages during Adempiere install
      • Nevertheless, the equinox osgi jar must stay intact in order to work, so I switched to only deploy the patch itself, not the supporting libraries re-packaged
    • An build file that, after having setup a build.properties does the re-packaging and deploying into an installed JBoss.

Adempiere Extension

  • This is an extension fragment to the system bundle (OSGi slang...)
  • It provides the ADempiere classes to the classpath of all plugins
  • It is merely declarative and contains no code

Adempiere Equinox bundle

  • This is a bundle that connects plugins to the ADempiere internals
  • It will provide the extension points for ADempiere
  • Currently, there are
    • ModelValidator
    • Form
    • Callout
    • Process
  • It implements and registers the so-called "host-service" that receives requests from the adempiere core and dispatches is to bundles, typically via extension points.
  • It implements and registers the "dictionary service", that uses PackIn to import PackOut.xml.
  • It provides a Plugin base class, AbstractAdempierePlugin, that handles install and startup:
    • If the plugin is started for the first time:
      • If /META-INF/PackOut.xml exists, it is PackedIn
      • If not, the plugin is manually registered as an imported package
      • The method install() of the bundle is called
    • The Method start() of the bundle is called (this substitutes start(BundleContext) from OSGi)
    • On stop, The Method stop() of the bundle is called (this substitutes stop(BundleContext) from OSGi)
  • So, if you want a full re-install of the plugin, you must increment the version number or delete the corresponding entry in "Imported packages"
  • Caution: Name and Version in the bundle header and in PackOut.xml must correspond!

The TestPlugin

  • This is a very simple plugin testing the above
  • Its activator does nothing
  • It provides extensions to the extension points ModelValidator, Callout and Process
  • The extension consists of a ModelValidator class (you wouldn't have thought so, would you?)

How to

Basics and JBoss Setup

  • Install an eclipse, checkout the ADempiere trunk (as adempiere) an install it.
    • adempiere/adempiere/Adempiere/jboss will then contain a jboss ready to run
  • The Code is in this branch: /branches/osgi/
    • There are several projects to be seperately checked out aside adempiereTrunk
  • Check the following libs at /branches/osgi/Adempiere-patch/lib/ are in your Adempiere-patch/lib:
    • org.eclipse.core.contenttype_3.3.0.v20080604-1400.jar
    • org.eclipse.core.jobs_3.4.0.v20080512.jar
    • org.eclipse.core.runtime.compatibility.auth_3.2.100.v20070502.jar
    • org.eclipse.core.runtime_3.4.0.v20080512.jar
    • org.eclipse.equinox.app_1.1.0.v20080421-2006.jar
    • org.eclipse.equinox.common_3.4.0.v20080421-2006.jar
    • org.eclipse.equinox.preferences_3.2.201.R34x_v20080709.jar
    • org.eclipse.equinox.registry_3.4.0.v20080516-0950.jar
    • org.eclipse.osgi.services_3.1.200.v20071203.jar
    • org.eclipse.osgi_3.4.2.R34x_v20080826-1230.jar
    • org.eclipse.update.configurator_3.2.201.R34x_v20080819.jar
  • edit Adempiere-patch/build.properties and set the path to the adempiere project
  • run Adempiere-patch/build.xml
    • It will instrument your Adempiere JBoss with the patch, all required equinox library and configurations
  • Open AdempiereEquinox/META-INF/MANIFEST.MF

EclipseExtPoint.PNG

    • The tab "extension points" contains the ModelValidator point.
    • Click on the third icon in the header ("Export deployable...") or in the menu File/Export/Plugin Development/Deployable plugins and fragments.

EclipseDeploy.PNG

    • Select AdempiereEquinox, AdempiereExtension and the TestPlugin for deployment
    • Choose as destination directory: <path to adempiere project>\adempiere\adempiere\Adempiere\jboss\server\adempiere\deploy\adempiere.ear\lib
    • Click Finish
    • In the ear deployment in JBoss, you should have a lib folder containing jar, a configuration folder and a plugins folder with the three plugins from above
  • Start your JBoss
    • Watch out for the lines:
INFO  [STDOUT] Starting Equinox...
INFO  [STDOUT] Listening on port 1234 ...
INFO  [STDOUT] Adempiere Host Bundle started
INFO  [STDOUT] Got Val Engine: ModelValidationEngine[Validators=#1, ModelChange=#1, DocValidate=#1]
INFO  [STDOUT] ModelValidator on: AD_User
INFO  [STDOUT] Hello World!!

Congrats! Your equinox container started, opened a telnet port, started the Host Bundle which in turn got a ModelValidation engine, found the TestPlugin listening on Table AD_User and registered it on the Engine.

  • Now fire up the ZK Web UI, login and change a user
    • You will see:
INFO  [STDOUT] ModelChange 2 on AD_User:1000000
INFO  [STDOUT] ModelChange 5 on AD_User:1000000
    • Phew! Adempiere plugin via equinox is working!
  • Now open TestPlugin/META-INF/MANIFEST.MF

EclipseExt.PNG

    • On the extension tab, you can see why it listens on AD_User: It was declared to the host bundle in the manifest!

Swing Client Setup

If you have successfully installed Equinox into your JBoss, making it available in the Swing Client is easy:

  • run Adempiere-patch/build.xml
    • Use the target dist-client for instrumenting your swing client
  • Repeat the plugin deployment script above, using $ADEMPIERE_HOME/lib destination directory
  • ... and eventually a nasty step: Edit the script $ADEMPIERE_HOME/lib/RUN_Adempiere.sh (or .bat) locate the line where the CLASSPATCH is set up and add $ADEMPIERE_HOME/lib/org.eclipse.osgi_3.4.2.R34x_v20080826-1230.jar to it.

Build your own plugin

  • simply create a new eclipse plugin project
  • use AdempiereEquinox as required bundle
  • register a ModelValidator class as the extension
  • deploy the plugin to JBoss as above
  • restart JBoss (or use the telnet session an stop/start the host bundle)

Form extensions

It is now possible to deploy swing forms via a plugin. To do this, create a plugin and specifiy some dependencies:

EclipseFormDep.PNG

Switch to the extension tab, click add and choose the AdempiereEquinox.Form extension point. Right-click on the new extension and choose New.../client. Create or select the class (must be of type FormPanel)

EclipseFormExt.PNG

Deploy the plugin. As usual, as SuperUser create a new Form, spüecifying the class as above and a new Menu entry. Try it!

WebForm extensions

This works essentially the same as for Form above, extending the point WebForm of course. Nevertheless, two things are different:

  • Since plugins essentially are deployed in the EJB layer but must have access to classes in the web layer (org.adempiere.webui.* and org.zkoss.*), the JBoss WAR classloader has to be turned off. This is a drawback since we no longer have classpath separation between web- and ejb-tier. You do this by switching the attribute UseJBossWebLoader to true in $JBOSS/server/adempiere/deploy/jboss-web.deployer/META-INF/jboss-service.xml.
  • You have to import several additional packages in your plugin, at least: org.adempiere.webui.component, org.adempiere.webui.panel,org.zkoss.zk.ui and org.zkoss.zk.ui.event.

See Also