OSGI Plugin Exported Packages, Fragments, and Extras documentation for the dotCMS Content Management System

Many plugins depend on other Java classes to function properly. The Java packages that your plugin depends on are called exported packages. When you create an OSGI plugin, you must tell the OSGI framework about these dependencies, so the framework can find the appropriate classes when running your plugin.

How to Specify Exported Packages

There are two basic ways that you can specify exported packages for your OSGI plugins within dotCMS:

  • Fragment Plugin: Creates a separate OSGI plugin which exports the packages that your main plugin needs.
  • OSGI Extras File: Places a list of your exported packages into a separate file which gets read on dotCMS startup.

You may manually edit the OSGI Extras file in the dotCMS back-end user interface by opening the Exported Packages Popup. However, if you do this manually, then each time you upgrade or patch dotCMS, the default OSGI Extras file will be overwritten, and you'll have to manually add your exported packages again.

Alternately, if you're running dotCMS in a containerized environment (Docker), you can maintain your OSGI Extras file in a separate location, and map it into your container. This allows you to persist your exported packages through upgrades and patches.

Advantages and Disadvantages

Each of these methods has some advantages and disadvantages, as outlined below:

MethodCan be Changed
Manually
Persists through
Restarts
Persists through
Upgrades/Patches
Can be Updated
Without dotCMS Restart
Updatable without
Access to File System
Exported Packages PopupYesYesNoYesYes
Persisted OSGI Exports fileYesYes1Yes1NoNo
Fragment PluginNoYesYes2YesYes
  1. If you use a containerized version of dotCMS with the OSGI extras file mapped appropriately, it will persist through patches and upgrades.
    • Otherwise, you may need to manually copy the file after a patch or upgrade to ensure it's accessible in the new version.
  2. Both your main plugin and your fragment plugin must be recompiled under the new version any time you upgrade.
    • However fragment plugins generally require no changes other than a simple recompile.

Choosing the Best Method

Which method is best for you will depend both on your development processes, and on which of these advantages and limitations are most important to you. Here are some general guidelines to consider.

If you don't have direct access to your server file system (such as when using the dotCMS Cloud service), we generally recommend that you use a Fragment Plugin.

  • Fragments persists through upgrades and patches, and allow you to update both your main plugin and your fragment plugin yourself, without the need to ask your server adminstrator for assistance, and without the need to restart dotCMS after updating the exported packages.

If you are using a containerized installation, and have direct access to your server filesystem, a persisted OSGI Extras file may provide the most benefits.

  • This allows you to keep the OSGI extras file outside of the dotCMS installation folder (so it won't get overwritten when upgrading or patching dotCMS), and then map it into your container.
  • However, if you don't have direct access to your server filesystem, then using this method will require that you ask your server administrator for assistance each time you make a change to the file.
    • Although you should not need to change your exported packages after an LTS patch install, you may need to modify the packages after a full version upgrade.

When you are first developing your plugin, you may wish to manually edit your exported packages via the Exported Packages popup window.

  • This makes it very easy to change your exported packages “on-the-fly”.
  • But we recommend that once you've finished your development, you switch to using Fragments or the OSGI extras file, because this method requires you to re-enter your exported packages each time you update your plugin or dotCMS, which is both time-intensive and error-prone.