DX OSGi Implementation

November 11, 2022

OSGi Framework startup

The OSGi framework is started using the org.jahia.osgi.http.bridge.StartupListener class which instantiates the FrameworkService. In turn, FrameworkService initializes Felix instances along with the ProvisionActivator which registers all the bundles that will initially be started and made available to all deployed bundles. Of particular note, FrameworkService loads its configuration from the felix-framework.properties file which contains important settings such as which packages are made available to all bundles. If you deploy a new JAR in Digital Experience Manager’s WEB-INF/lib, you will need to update the felix-framework.properties file so that the packages present in the new JAR are properly made accessible (see Appendix 1 - Configuring a module that extends the system for more information)

OSGi Servlet Bridge

The OSGi servlet bridge actually consists of two parts, a proxy servlet that is mapped as a servlet in the WEB-INF/web.xml file of the Digital Experience Manager web application and then the actual bridge that will make it possible to call "regular" servlet inside the OSGi framework.

Digital Experience Manager Module Extender

The core of the module integration is in the jahia/bundles/jahiamodule-extender project. Here the Activator class is the starting point, that registers the bundle listeners to listen for the deployment and undeployment of bundles and does all the registration work inside Digital Experience Manager. This is where most of the OSGi "magic" is happening, including the registration and dispatching to JSPs.

Bundle packaging

The default-packaged installation of the OSGi bundles is done in the jahia/war project, in the pom.xml file. We deploy to two directories: WEB-INF/bundles for the "system" bundles, meaning the ones we think will not change often, and WEB-INF/var/bundles which is a watched directory by the FileInstall bundle and that will listen for any changes of deployment. It is of course also possible to say that we want additional directories to be watched, this is very easy to do with the FileInstall bundle (documentation is here : http://felix.apache.org/site/apache-felix-file-install.html).

OSGi and Digital Experience Manager Module States

Bundle life cycle

With the installation of a bundle in the OSGi runtime the bundle is persisted in a local bundle cache. The OSGi runtime then tries to resolve all dependencies of the bundle.

If all required dependencies are resolved, the bundle is in the RESOLVED status otherwise it is in the INSTALLED status.

If several bundles exist which would satisfy the dependency, then the bundle with the highest version is used. If the versions are the same, then the bundle with the lowest install ID will be used (the bundle gets a unique identifier assigned by the framework during the installation). If the bundle is started, its status is STARTING. Afterwards it gets the ACTIVE status.

This life cycle is depicted in the following graphic:

Digital Experience Manager extends the default OSGi lifecycle states to add intermediary states that detail the state in which a module is. You can find the description of these states in the following table.

State name OSGi Digital Experience Manager Description
UNINSTALLED x   Bundle is not installed
UNRESOLVED x   Bundle is installed, but dependencies haven’t been resolved
RESOLVED x   Bundle is installed and all dependencies have been resolved
WAITING_TO_BE_PARSED   x Bundle is started but it depends on other Jahia modules for content definitions
PARSED   x Bundle is started and all its content definitions have been parsed
INSTALLED x   Bundle was installed, but not started
UPDATED x   Bundle was updated
STOPPED x   Bundle was stopped
STOPPING x   Bundle is stopping
STARTING x   Bundle is starting
WAITING_TO_BE_STARTED   x Bundle is waiting to be started, waiting for another module to be started
WAITING_TO_BE_IMPORTED   x Bundle is waiting to import its content, waiting for a dependency to import its content
ERROR_DURING_START   x An error occurred during Jahia module start
STARTED x   Bundle is fully started and available