We've been noticing more and more discussion on Jivespace about people migrating older customizations to the new Clearspace 2.x architecture along with quite a few people writing new customizations. I thought that now would be a good time for a refresher series of posts on customizing for Clearspace 2.x


Clearspace version 2 includes a few big changes to the conventions and frameworks on which Clearspace is built. Many of these changes were made to improve Clearspace extensibility by letting the application and extensions be more loosely coupled -- and so be more durable during upgrade. Other changes that impact customizations were simply feature improvements in which some change to code is required.


Here's a high-level list of the changes that effect extension and customization code:


  • Clearspace was migrated to the Spring framework. This has both broad and deep effects on code written to run on Clearspace; such code must use the same conventions in order to integrate well. The changes include API refactoring to support dependency injection and integration of Spring modules (for security and transaction management, for example).

  • Clearspace was migrated from WebWork2 to Struts2. This has broad impact on plugins, but the changes are relatively small  -- primarily effecting syntax in FreeMarker templates and configuration files.

  • Widgets were enhanced to support use in multiple contexts, rather than just space overview pages. Changes to widget development support this new feature.

  • The macro-related API was narrowed to the area documented in version 1, essentially excluding an undocumented area that some people used. Also, macros must now return HTML that qualifies as well-formed XML.

  • Web services support is now provided through CXF, an evolution of XFire (the version 1 technology). A larger change results from the migration to Spring, which makes integrating new web services a bit more complex.

  • Custom user data providers are now based on a streamlined API. These must be rewritten, but the new model is much simpler.

  • Custom authentication providers are now based on Spring through Acegi. The change is pretty significant, including new API and configuration conventions.

  • Myriad API changes resulted from the migration to Spring and from an effort to streamline and modularize the Clearspace API. These include support for the projects feature, refactoring manager interfaces, content handling, and conventions such as dependency injection.


For those extensions and customizations deployed as plugins (widgets, actions, macros, and web services), there are a few changes in version 2 with broad effect.


  • Migration from WebWork to Struts means replacing your xwork-plugin.xml with a struts.xml

  • Migration to Spring means adding a spring.xml for certain kinds of Spring support.

  • One benefit of the new model is that modifying your plugin.xml, struts.xml, or spring.xml will provoke Clearspace to reload your plugin. This can be handy for debugging.

  • Support for a <maxserverversion> element was added. Similar to the <minserverversion> element, use the new one to specify that highest Clearspace version on which your plugin is supported. This can be useful when you want to ensure that upgrades to Clearspace prompt the plugin's users to upgrade the plugin also.

  • Plugin life cycle methods changed. If you used the version 1 com.jivesoftware.base.Plugin interface, you'll notice that its two methods have changed in order to support Spring. Semantics for the methods is unchanged.

    • Plugin.initialize(PluginManager, PluginMetaData) is now Plugin.init, a method without parameters. Use Spring dependency injection to receive a PluginManager instance; you can retrieve a PluginMetaData instance from the manager.

    • Plugin.destroyPlugin is now Plugin.destroy.


The information above along with more details can be found in the Upgrading Extensions to 2.0 documentation.