Jahia OSGi Implementation
OSGi Framework startup
The OSGi framework is started once Jahia spring context is instantiated. In turn, FrameworkService initializes the Apache Karaf instance 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 digital-factory-data/karaf/etc/config.properties file which contains important settings such as which packages are made available to all bundles.
OSGi Servlet Bridge
The OSGi servlet bridge consists of two parts, a proxy servlet that is mapped as a servlet in the WEB-INF/web.xml file of the Jahia web application and then the actual bridge that will make it possible to call “regular” servlet inside the OSGi framework.
Jahia 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 Jahia. This is where most of the OSGi “magic” is happening, including the registration and dispatching to JSPs.
Bundle packaging
We can have both system bundles that will be handled by Apache Karaf (such as Apache Karaf extensions) and Jahia bundles (common Jahia modules).
We are relaying on Apache Karaf for system bundle. All the system bundles are in the Apache Karaf folder, by default located in digital-factory-data/karaf. From here you can use all the Apache Karaf framework to deploy any bundle / feature / kar file. See more information here:
https://karaf.apache.org/manual/latest
Jahia has a also watched directory located in digital-factory-data/modules that contains all dx installed bundles
OSGi and Jahia 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:
Jahia 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 | Jahia | Description |
|---|---|---|---|
| UNINSTALLED | x | Bundle is not installed | |
| UNRESOLVED | x | Bundle is installed, but dependencies haven’t been resolved | |
| RESOLVED | x | 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 [removed in DX 7.2.0.0] | |
| PARSED | x | Bundle is started and all its content definitions have been parsed [removed in DX 7.2.0.0] | |
| INSTALLED | x | x | Bundle was installed, but not started |
| UPDATED | x | x | Bundle was updated |
| STOPPED | x | Bundle was stopped | |
| STOPPING | x | x | Bundle is stopping |
| STARTING | x | x | Bundle is starting |
| WAITING_TO_BE_STARTED | x | Bundle is waiting to be started, waiting for another module to be started [removed in DX 7.2.0.0] | |
| 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 [removed in DX 7.2.0.0] | |
| STARTED | x | x | Bundle is fully started and available |
| SPRING_STARTING | x | Bundle is started but is waiting for spring context to be available [since DX 7.2.0.0] | |
| SPRING_NOT_STARTED | x | Module failed to start due to an error creating module's Spring context [since DX 7.2.0.0] | |
| INCOMPATIBLE_VERSION | x | The Jahia required version of the module is incompatible with the current one | |
| ERROR_WITH_DEFINITIONS | x | Bundle cannot start due to definitions error | |
| ERROR_WITH_RULES | x | Module failed to start due to an error compiling included business rules (Drools) [since DX 7.2.3.1] |
Listening to bundle states
It is possible to listen to module state changes in another bundle by implementing a BundleListener. It's quite a common way to detect features in other bundles and react when they are installed / started.
However, you must be careful with these as BundleListener are asynchronous, and at the time your listener will be executed the state of the module may have changed. If you need to listen to a state change, and want to be sure that the state has not changed again - or if your listener do any operation that might change the state of a bundle, please consider using SynchronousBundleListener instead.