Jivespace Community Blog

Customizations in Clearspace 2.x Part One

communities@jivesoftware.com — Tue, 24 Jun 2008 20:00:29 GMT

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.

Theming in Clearspace 2.0

communities@jivesoftware.com — Mon, 12 May 2008 16:58:01 GMT

As you know, we changed a few things in our underlying architecture for Clearspace 2.0, including some changes in the Freemarker templates as a result of moving from Webwork to Struts along with some other changes. In this video, Matt Walker, Professional Services Engineer at Jive Software, talks about the process of upgrading existing themes along with plenty of best practices to make your themes more easily upgradeable in the future.

Matt also did an earlier screencast as an Introduction to Skinning Clearspace, which you might also want to watch along with this video.

You can also download the Quicktime version (Caution: file is ~200MB), or you can watch a larger version online, which will improve readability of embedded screenshots (recommended).

The entire presentation is also attached below as a PDF file.

How and Where we used the Spring framework in Clearspace 2.0

dolan.halbrook@jivesoftware.com — Thu, 20 Mar 2008 19:55:01 GMT

For those of you who are fans of Spring, or those who are just plain curious, I'd like to briefly go over the parts of the framework we used in the latest release of Clearspace. One of our goals for the new release was to take advantage of the power the framework offered where it made sense to us, and in the end it turned out Spring and Clearspace are a good fit for eachother.

Core Context and Struts: The JiveContext now extends the Spring ApplicationContext. Everything registered with the context is a Spring bean. Struts actions and interceptors are autowired using these bean definitions. Writing Actions just got a whole lot simpler.

Data Access: We changed a lot of our code to use Spring's JdbcTemplate and SimpleJdbcTemplate. This has the advantage of making our DAO code much simpler and less error prone, as well as quicker to write. Some classes ended up half the size after this effort. We used annotation-based transactions, wired in using Spring's AspectJ support via the AnnotationTransactionAspect. This allowed us to quickly add transactional coverage of far more DAO methods than before, and more easily make methods transactional in future development. Finally we used Spring's LDAPTemplate in several places to simplify directory access code.

Security: We're using Acegi (Spring Security) for authentication. This allows the possibility to authenticate against more than one data store. For example, you could have one account that authenticates against LDAP, and a separate machine account that authenticates against a database. It also provides a well documented, peer-reviewed framework to use as a platform for developing custom authentication solutions. We are investigating using Acegi more fully for authorization in future releases.

Tasks: We worked hard to externalize timed tasks so that they each have bean definitions. This gives greater insight into what is being fired, why, and where. It also makes it much easier to control when a task is firing, or turn it off completely for testing purposes.

Plugins: We allow plugins to add their own Spring bean definitions to the context, so that Plugin actions and interceptors can be autowired as expected. This is done via the plugin's "spring.xml" file.

Web Services and AJAX: Apache CXF is now used to expose SOAP and REST style web services. It relies heavily on Spring for its configuration. We are also using Spring for DWR configuration, via the Spring 2.0 DWR namespace.

Customizations: As part of the new release we also parse any XML file in the <jive home>/etc directory with the expectation that it's a Spring configuration file. Developers can use this to extend or override bean definitions in the core application context.

In the end, we found Spring very helpful to simplifying our codebase and providing a point of cohesion. We look forward to using it even more fully as we continue to develop Clearspace, and as the Spring framework itself evolves.