Skip to main content
View as Markdown

How iDempiere uses OSGi

iDempiere has used OSGi for more than ten years, and the way plug-ins are written changed a lot in that time. This page explains how it changed. It also tells you which parts of a plug-in are OSGi standard, which come from Eclipse, and which are iDempiere's own.

It helps when you read old forum posts, old plug-ins or the older guides, because they often show an older way of doing the same thing. For the terms, see the OSGi Glossary.

How it changed​

The dates below come from the commit history of the iDempiere source code. Each row names the Jira ticket when there is one.

WhenWhat changedWhat it means for you
January 2010The code base starts to run inside Equinox, the OSGi framework of Eclipse.The first step to bundles.
August 2010Support for Declarative Services on Equinox is added.Components can be described in XML files.
September 2010Projects are renamed to match their bundle symbolic names, and the build moves to Eclipse features and a product configuration.One bundle per project, delivered as features.
December 2010System events are built on the OSGi Event Admin service. The first component XML file appears in OSGI-INF/.Event handlers are OSGi services.
November 2012 to February 2013IDEMPIERE-359 adds OSGi services as a second way to extend core, next to the Eclipse extension points of plugin.xml. Service.locator() then looks services up in the OSGi service registry.A plug-in can publish a service instead of declaring an extension point.
October 2019The first @Component annotation appears in the source (IDEMPIERE-4056).Components no longer need hand-written XML.
February 2021Factory base classes backed by a Map and lambdas are added: IDEMPIERE-4675 for models, IDEMPIERE-4689 for processes and IDEMPIERE-4690 for callouts.You can register a model, process or callout with a factory that holds a map of names to lambdas.
February to October 2021Annotation-based registration is added. IDEMPIERE-4694 adds annotation-based event handlers, IDEMPIERE-4773 forms and IDEMPIERE-5001 (October) the @Process annotation with AnnotationBasedProcessFactory. The class scanner ClassGraph first appears with IDEMPIERE-4842.You can register a model, process, callout, event handler or form by annotating the class. See the iDempiere 9 feature pages.
January to May 2026Parts of core move behind services or into their own bundles: accounting (IDEMPIERE-6793), the SOAP web services (IDEMPIERE-6955), an extension manager (IDEMPIERE-6908) and Redis as an alternative to Hazelcast for the distributed cache (IDEMPIERE-6989).Core depends less on its own implementations, and optional parts install as extensions.

What is standard OSGi, and what is not​

A plug-in mixes three kinds of things. Knowing which is which tells you where to look for help.

KindExamples in iDempiereWhere to read more
OSGi standardBundles and MANIFEST.MF, BundleActivator, the service registry, Declarative Services (@Component, @Reference, @Activate), Event Admin, fragment bundles (Fragment-Host)The OSGi specifications
Eclipse and EquinoxThe Equinox framework, plugin.xml and extension points, features and p2 repositories, the Eclipse project and PDE toolsThe Eclipse documentation
iDempiere's ownService.locator(), the factory pattern (IModelFactory, IProcessFactory and similar), the mapped factories built on a Map and lambdas, class scanning with ClassGraph, AbstractEventHandler, the extension managerThe plug-in guides on this site

Two things surprise newcomers:

  • The annotations you write are standard OSGi, but the way iDempiere finds the classes that carry its own annotations, such as @Callout or @Process, is iDempiere's own code. It scans packages, which is why a factory has a getPackages() method.
  • The older Eclipse extension points have not disappeared from the source. plugin.xml files in core bundles still declare extension points such as org.adempiere.base.ModelValidator and org.adempiere.webui.Form. New plug-ins use services instead, as the guides show.

What this means when you write a plug-in​

  • Use services and annotations. Publish a service with @Component. This is the way the current guides teach, and it needs no XML.
  • Expect older examples to differ. An old plug-in may use a BundleActivator to register things in start(), a hand-written file in OSGI-INF/, or a plugin.xml extension point. They still show what the code does, but write new code the current way.
  • Check the version. The annotation-based factories, such as AnnotationBasedProcessFactory, exist from iDempiere 9. For an older version, register a factory with a @Component service as the process guide shows, or with an activator and XML.
  • Ask in the right place. For @Component and @Reference questions, the OSGi Declarative Services documentation applies. For "which factory do I implement", the iDempiere guides apply.