Most plugins depend on other Java classes to function properly and the Java packages that hold those classes that your plugin requires to run are called exported packages. When you create an OSGi plugin, you must tell the OSGi framework which packages from the system classloader to export or make available for your plugins. If you do not export the packages your plugin needs to function, your plugin will fail to start in OSGi.
How to Specify Exported Packages
There are two basic ways that you can specify exported packages for your OSGi plugins within dotCMS:
Fragment Plugins:
Creates a separate OSGi plugin which exports the packages that your main plugin needs. The packages exported by your fragment(s) are automatically added to the list of packages that OSGi exports. In previous versions of dotCMS, this was the default way to export packages and many of the example plugins still automatically generate a fragment jar when building.
OSGi Extras File:
The OSGi extras file is a list that tells OSGi what to export by default. The file gets read automatically on dotCMS startup and when you restart the OSGi framework. You may manually edit the OSGi extras file from the plugin screen in the dotCMS back-end. The resultant exported packages file is shared across all dotCMS instances in a cluster and will persist over restarts and upgrades.
Advantages and Disadvantages
Each of these methods has some advantages and disadvantages, as outlined below.
Fragments are a good choice for plugin portablilty and development. You can upload an OSGi plugin and its fragement jar into different dotCMS instances and the plugin will (should) fire up and run. The downside of fragements is that they automatically force OSGi to reinitialize whenever they are read or added, which results in OSGi-based functionality to be unavailable for a few seconds until the process is complete. This means that every time OSGi loads a fragment jar, it reinitializes the whole OSGi framework. If you have multiple fragement jars from various OSGi plugins, it will force OSGi to reinitialize multiple times.
The OSGi Extras File is a good choice in productions environments, as once you have made changes to the file that exports the packages your OSGi plugins need, you can update or reload the plugin .jars as often as needed without having to reinitialize the entire OSGi framework. When a plugin is uploaded, dotCMS will automatically read the OSGi imports from it, will automatically update the OSGi extras File based these imports and finally reinitialize the framework if there are new exports. If there are no new exports, dotCMS will not reinitialize the framework. This process works fairly well, though it might require you to add one or more packages manually.
If you do edit the OSGi extras file in the UI, you will need to reinitialize the OSGi framework for your changes to be picked up. Once once that is done, your OSGi extras file will be persisted in the shared /assets directory and will survive both upgrades and restarts.
