OSGI / Dynamic Plugins - Documentation topics on: development,integration,osgi,plugins,.

OSGI / Dynamic Plugins

The OSGI (Open Services Gateway Initiative) framework is a module system and service platform for the Java programming language that implements a complete and dynamic component model. Applications or components (coming in the form of bundles for deployment), can be remotely installed, started, stopped, updated, and uninstalled without requiring a reboot. The OSGI service registry detects the addition of new bundles, updated bundles, or the removal of bundles, and reloads accordingly.

OSGI support allows the hot deployment of Viewtools, Actionlets, Services, Servlets, Custom Admin Portlets, Override classes, Spring Views and Controllers, Content Hooks and more. dotCMS also provides a Dynamic Plugins UI Portlet and Tooling that allows OSGI plugin bundles to be deployed, undeployed, and managed from the dotCMS backend.

dotCMS implements OSGI using the Apache Felix Library.

Please select the section below for more information on managing OSGI plugins in dotCMS:

Controlling OSGI Startup

Enabling and Disabling OSGI

OSGI support is enabled by default in dotCMS. To disable OSGI in your dotCMS instance, add the felix.osgi.enable property to the dotmarketing-config.properties file and set it to false:


Note: It is strongly recommended that all changes to the dotmarketing-config.properties file be made through a properties file extension.

Delaying OSGI Startup

By default, the OSGI plugin thread is started during the initial dotCMS startup, before dotCMS is fully initialized and (if you start from an empty database) before the starter site is initiated. This allows you to create OSGI plugins which interact with or affect the dotCMS startup process.

However many OSGI plugins do not need to interact with the startup process, and require some dotCMS services which may not be fully available until after other dotCMS startup tasks have been completed. To ensure that these plugins have access to all dotCMS services, you may delay the OSGI startup using the felix.osgi.init.delay and felix.osgi.wait.for.dotcms properties in the dotmarketing-config.properties file.

Note: It is strongly recommended that all changes to the dotmarketing-config.properties file be made through a properties extension file.


The OSGI thread will be delayed in different ways depending on how both of these properties are set:

felix.osgi.init.delayfelix.osgi.wait.for.dotcmsDelay Behavior
0false(Default values). OSGI initialization is not delayed (OSGI will initialize inline, as it has in previous versions).
> 0falseWait the specified time (in ms) before initiating OSGI.
0trueWait until after the InitServlet has finished before initiating OSGI.
> 0trueWait until the InitServlet has finished; After InitServlet has finished, wait the specified time (felix.osgi.init.delay) before intiating OSGI.

Note: Any time OSGI initialization is delayed, dotCMS still immediately spawns the OSGI thread early in the dotCMS startup. However when a delay is configured, the OSGI thread does not begin initiating the OSGI plugins until after the delay is completed.

File Locations

Felix Install Folder

By default, the Felix install folder is {DOTCMS_ROOT_PATH}/WEB-INF/felix.

You may change the location of the Felix install directory by adding the felix.base.dir property to the dotmarketing-config.properties file. The value of the property should be an absolute path to a directory on the File System where dotCMS is installed.

Note: It is strongly recommended that all changes to the dotmarketing-config.properties file be made via a properties extension file.

Felix Subfolders

The dotCMS OSGI implementation uses four subfolders within the Felix install folder:

felix/bundleIncludes the runtime and core of the OSGI (6 jars).
These should not be deleted or modified.
felix/felix-cacheStores the cache for the implementation.
Can be safely deleted if you encounter issues when deploying a new class.
felix/loadHot deploy directory.
If you copy a bundle to this directory it will be detected by OSGI and deployed automatically.
felix/undeployedStores bundles which have been undeployed (from the Dynamic Plugins portlet).

To override and externalize the location of felix subfolders please see the Distributed OSGI Bundles documentation.

Distributed OSGI Bundles

For information on how to override the felix base path, override the location of felix subfolders, and externalize OSGI plugin customizations, see the Distributed OSGI Bundles documentation.

The Dynamic Plugins Portlet

dotCMS provides a web interface to manage OSGI plugin bundles. To access the portlet, select Dev Tools -> Plugins. (Note: If you do not have the Plugins option in the Dev Tools tool group, you may add the portlet manually).

List Plugins

The Dynamic Plugins screen displays a list of all the plugins currently deployed:

Plugins which have been loaded but which were previously undeployed do not display in this list. Please see Load Plugins, below.

You may Start, Stop, or Undeploy each plugin by selecting the appropriate option in the Actions column to the right of the plugin.

Upload Plugins

To upload and deploy a new plugin, click Upload Plugin:

Note: When you upload a plugin it is automatically deployed.

Load Plugins

You can load a plugin that has been previously undeployed by selecting the plugin from the Available Plugins drop down. All plugins in the folder undeployed folder will display in this list.

Restart Plugins

  • To restart an individual plugin, first select Stop, then select Start.
  • To restart the OSGI framework, press the Restart Framework button.
    • Note that this restarts all OSGI plugins; when possible, it is recommended that you restart individual plugins instead.

View and Edit Exported Packages

Your OSGI plugins may access any dotCMS packages which have been exported. If you add a new OSGI package, you may need to add additional packages to the list of exported packages to ensure your plugin has access to all packages it needs.

To view the list of packages dotCMS exposes to the OSGI context, select Exported Packages.

To add packages to the list:

  1. Add a comma to the last package in the list.
  2. Add each new package to the list, separating packages with commas.
  3. Press the Save Packages button.