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
- File Locations
- The Dynamic Plugins Portlet
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.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:
|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.
Felix Install Folder
By default, the Felix install folder is $DOTCMS_HOME/tomcat-X.x.xx/webapps/ROOT/WEB-INF/felix/.
You may change the location of the Felix install directory by adding the
felix.fileinstall.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.
The dotCMS OSGI implementation uses four subfolders within the Felix install folder:
|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.
|felix/undeployed||Stores bundles which have been undeployed (from the Dynamic Plugins portlet).|
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).
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.
To upload and deploy a new plugin, click Upload Plugin:
Note: When you upload a plugin it is automatically deployed.
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.
- 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.
- Developing an OSGi Plugin
- OSGI (Dynamic) Plugin Logging
- Content Hook / ContentAPI Interceptor Plugin
- Servlet and Filter Plugin
- OSGi Services Plugin
- Spring Controller Plugin
- Add Rewrite Rule Plugin
- Scheduled Quartz Job Plugin
- Custom Workflow Action Plugin
- Override a dotCMS Class Plugin
- Spring Libraries Plugin
- Custom Admin Portlet Plugin
- Actionlet - Rules plugin
- Conditionlet - Rules plugin
- Third Party Jars and Libraries Plugin
- Custom Velocity Viewtool Plugin
- Fragment/Exported Packages Plugin
- Using Hibernate in OSGI Plugins