Java Development documentation for the dotCMS Content Management System

This documentation section explains how to setup a java development environment to customize or extend dotCMS. The recommended way to extend dotCMS is through the use of plugins. Developing customizations using plugins isolates custom code from the core of dotCMS and helps to insure a clean upgrade path moving forward.  In dotCMS there are two different kinds of plugins that serve different purposes.


Plugins in dotCMS are not like plugins in many other applications such as browsers, where there is a sandbox around the plugin to protect against problems with the plugin.

  • By definition, plugins override dotCMS code.
    • This means they can not be sandboxed for safety.
    • This makes them more like operating system drivers - which give you the flexibility to change anything, but also the potential to break existing functionality in ways that dotCMS can not protect against.
  • All plugins run the risk of breaking existing dotCMS functionality.
    • Although many plugin changes can be done relatively safely, there is always a chance that, when you activate your plugin, your dotCMS installation will not work properly.
    • If this happens, you will need to uninstall your plugin and fix the problem.
    • Both static plugins and OSGI plugins can be uninstalled by modifying files in the dotCMS installation folder; for more information, please see the documentation referenced below.

Dynamic OSGI Plugins

OSGI Plugins can be deployed and hot-swapped at runtime without needing an application server restart/reload. OSGI plugins:

  • Are easy to develop and deploy on a running dotCMS system.
  • Provide methods to easily implement new functionality in dotCMS via understandable extension points.
  • Provide a separate class loading environment in which you can deploy different versions of common libraries used by dotCMS (other than those provided by dotCMS out of the box).
  • Can interact with dotCMS's classloader to override any class inside dotCMS.
  • Can be Push Published between environments.
  • Are stored as plain OSGI bundles.

Static Plugins (Deprecated)

Static plugins are deployed at configuration time and require an application server restart/reload for them to take effect. Static plugins allow you to:

  • Override any file in the dotCMS distribution.
    • This makes them an ideal way to Config your dotCMS installation.
    • Using plugins to modify your configuration makes your dotCMS configuration portable, repeatable, and easily upgradable.
  • Override any code in the dotCMS code base.
  • Provide .jar and packages directly to your App server (e.g into the /endorsed folder).
  • Easily interact with the dotCMS dotCMS classloader and Singletons running within dotCMS.
  • Patch an existing dotCMS installation without the need to fully upgrade to the latest dotCMS version.

For dotCMS Cloud Customers: By default, Static plugins are not supported on dotCMS Cloud instances. Static plugin support can be provided for dotCMS Cloud as an additional option; for more information, please contact dotCMS.

Integrated Development Environments

While it's not strictly necessary, we recommend that you use an IDE while developing plugins. We provide specific instructions on how to get started with one IDE in the Setting up the Development Environment documentation, but you can use other IDEs to suit your preference.