dotCMS plugins are built using OSGi, which can include a combination of java classes, jars, static assets, html, velocity, what have you. dotCMS plugins are hot-loadable, meaning they can be installed at runtime and do not require a server restart to take effect.
The OSGi (Open Services Gateway Initiative) framework is a module system and service platform 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.
dotCMS plugins allows the hot deployment of REST endpoints, Viewtools, Actionlets, Services, Interceptors (servlets and filters), Custom Admin Tools, Override classes, Content Hooks and more. dotCMS also provides a plugin screen 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:
felix.osgi.enable=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 configuration changes be made through environmental variables.
felix.osgi.init.delay=0
felix.osgi.wait.for.dotcms=false
The OSGi thread will be delayed in different ways depending on how both of these properties are set:
| felix.osgi.init.delay | felix.osgi.wait.for.dotcms | Delay Behavior |
|---|---|---|
| 0 | false | (Default values). OSGi initialization is not delayed (OSGi will initialize inline, as it has in previous versions). |
| > 0 | false | Wait the specified time (in ms) before initiating OSGi. |
| 0 | true | Wait until after the InitServlet has finished before initiating OSGi. |
| > 0 | true | Wait 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:
| Subfolder | Description | Notes |
|---|---|---|
| felix/bundle | Includes the runtime and core of the OSGi (6 jars). | These should not be deleted or modified. |
| felix/felix-cache | Stores the cache for the implementation. | Can be safely deleted if you encounter issues when deploying a new class. |
| felix/load | Hot deploy directory. | If you copy a bundle to this directory it will be detected by OSGi and deployed automatically. Important: If you remove a plugin from the load directory via the file system, you must Restart Framework in the Plugins Tool so that the references of the plugin are deleted. |
| felix/undeployed | Stores bundles which have been undeployed from the Dynamic Plugins Tool. |
To override and externalize the location of felix subfolders please see the Distributed OSGi Bundles documentation.
Changing File Locations
You can override the felix base path to set a custom directory path, even one outside the dotCMS distribution folder. This may be useful in dotCMS deployments via Docker containers.
To change the felix base path, set the following property (in the dotmarketing-config.properties file, or via an environment variable):
felix.base.dir=/usr/deploy/felix
Folder Creation
Upon startup, if the specified folder does not already exist, it will be created and will contain the following subdirectories:
/felix(as defined byfelix.base.dirproperty)/bundle/felix-cache/load/undeployed
If the specified path can not be created for any reason, the base path will default to WEB-INF/felix (from the root of the dotCMS installation folder, e.g. dotserver/tomcat-X.x.xx/webapps/ROOT in the standard dotCMS distribution).
Changing Individual Subfolder Paths
When you change the Felix base path, by default, all subfolders will be set from the base path; so, for example, if you set the base path to /usr/local/felix, then the Load folder will be set to /usr/local/felix/load. You may, however, change the locations of individual subfolders if you wish, using additional properties. The following table lists all the properties which control the locations of the base directory and all Felix subfolders:
| Felix Folder | Property | Default Value | Description |
|---|---|---|---|
| Base Directory | felix.base.dir | {DOTCMS_ROOT_PATH}/WEB-INF/felix | The base path of the felix directory. |
| Bundles | felix.felix.auto.deploy.dir | {DOTCMS_ROOT_PATH}/WEB-INF/felix/bundle | Bundle file location. |
| Cache | felix.org.osgi.framework.storage | {DOTCMS_ROOT_PATH}/WEB-INF/felix/felix-cache | Cache file location. |
| Load | felix.felix.fileinstall.dir | {DOTCMS_ROOT_PATH}/WEB-INF/felix/load | Location to place dynamic plugins to auto-load them. |
| Undeploy | felix.felix.undeployed.dir | {DOTCMS_ROOT_PATH}/WEB-INF/felix/undeployed | Where undeployed plugins are stored |
Note: Any of the paths can be referenced using local paths, symbolic links, or environment variables.
The Dynamic Plugins Tool
dotCMS provides a web interface to manage OSGi plugin bundles. To access the Tool, select Dev Tools -> Plugins. (Note: If you do not have the Plugins option in the Dev Tools tool group, you may add the Tool manually).
List Plugins
The Dynamic Plugins Tool 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:
- Add a comma to the last package in the list.
- Add each new package to the list, separating packages with commas.
- Press the Save Packages button.
- Important: Selecting Save Packages will restart the OSGi framework.
