This page last changed on Dec 07, 2006 by mryall.

There are three main persistence APIs which are used in Confluence:

  1. Hibernate - database persistence, difficult to extend.
  2. Bandana - XML persistence, easy to use in plugins. Stored in database in Confluence 2.3+, or in Confluence home directory in 2.2.x and earlier.
  3. Content properties - database persistence for properties associated with a piece of Confluence content.

Because Bandana is the primary persistence API used by plugin developers, it will be covered in more detail below.

Hibernate

Confluence uses the open source persistence framework Hibernate. Confluence 2.2.x uses Hibernate version 2.1.8.

Each object to be persisted has a *.hbm.xml file which sits in the same directory as the associated class in the Confluence web application. For example, Label.class has an associated Label.hbm.xml which describes how label objects will be persisted. The particular details vary from class to class, but typically include:

  • the database table used to hold the data (Confluence bootstrap creates these tables if they do not exist)
  • the column names and mappings to class attributes
  • any special queries used for functionality in Confluence (for example, to retrieve a list of personal labels)

All this data is expressed in the standard Hibernate mapping format. In some cases, there is a single mapping file for all subclasses of a particular class. For example, ContentEntityObject.hbm.xml includes mappings for pages, news, mail and space descriptions.

The Hibernate mapping files are listed in mappingResources bean in applicationContext.xml.

Although it might be possible to extend Confluence's database through Hibernate, this is not recommended. There are a few downfalls with extending our Hibernate configuration:

  1. You need to maintain your forked copy of the hibernate mappings file against each new version of Confluence
  2. Your new hibernate objects will not be protected from (or necessarily upgraded to) any changes we make in the schema in future versions
  3. Unless you really understand our code, something weird will happen.

Avoid using Confluence's database to store custom data – use content properties or Bandana instead.

Bandana

Bandana is an Atlassian framework for persistence which uses XStream to convert arbitrary Java objects into XML for storage. The concepts used in Bandana are very simple:

  • Bandana stores data in contexts. In Confluence, there is one global context, and one context per space. The relevant class is ConfluenceBandanaContext.
  • Each context stores key-value pairs. The key is a String and the value can be any Object (it should typically implement Serializable).

Based on this design, the BandanaManager has methods for storing and retrieving values from a context by key:

  • void setValue(BandanaContext context, String key, Object value) - store a value against a key in the Bandana context.
  • Object getValue(BandanaContext context, String key) - get a key's value from the Bandana context. Returns null if no matching context and key exists.
  • Object getValue(BandanaContext context, String key, boolean lookUp) - same as above, except if lookUp is true and the context is a space context, this method will also check the global context if no matching key is found in the space context.

For plugins, it is recommended to use a key for your Bandana values that includes the full package name of your plugin. For example, a theme plugin might use a key like org.acme.confluence.mytheme.importantPreference.

Prior to Confluence 2.3, this XML was written to the filesystem in the Confluence home directory. The file config/confluence-global.bandana.xml stores the global context, and there is a file config/spaceKey/confluence-space.bandana.xml with the configuration for each space. In Confluence 2.3 and above, Bandana data is written to the BANDANA table in the database, with three columns for context, key and an XML-serialized value.

To get access to the BandanaManager from your plugin code, normally you only need to include a private BandanaManager field with an associated setter method. Spring will automatically call the setter method before the first time your plugin is called.

public class MyMacro extends BaseMacro {
    private BandanaManager bandanaManager;

    // setter called by Spring
    public void setBandanaManager(BandanaManager bandanaManager) {
        this.bandanaManager = bandanaManager;
    }

    // main method of macro
    public String execute(...) {
        // do stuff with bandanaManager
        return "...";
    }
}

Content properties

Another form of persistence, content properties are key-value pairs associated with a ContentEntityObject and stored in the database.

There is another issue for plugins, specifically if they have been installed by being uploaded (or more recently, via the Plugin Repository). If you try to store an object which is defined in the plugin, it will fail when you try to retrieve it because the BandanaManager was created by a ClassLoader which has no knowledge of the plugin's classes.

The solution/workaround is to convert your object to an XML string via XStream before you stick it in Bandana. Something like this:

// Store the object
XStream xStream = new XStream();
xStream.setClassLoader(getClass().getClassLoader());

String xml = xStream.toXml(myObject);
bandanaManager.setValue(ctx, key, xml);

// Later, retrieve the object
myObject = (MyObjectClass)xStream.fromXml(bandandaManager.getValue(ctx, key));

The key is to set the class loader to the plugin's class loader. You'll also want to add a null-check on any getValue response...

Posted by david@randombits.org at Aug 14, 2006 09:41

Prior to Confluence 2.3, this XML was written to the filesystem in the Confluence home directory. The file config/confluence-global.bandana.xml stores the global context, and there is a file config/spaceKey/confluence-space.bandana.xml with the configuration for each space. In Confluence 2.3 and above, Bandana data is written to the BANDANA table in the database, with three columns for context, key and an XML-serialized value.

Does this mean that the space scope is now lost, so that the key a.b.c when looked up from a global BandanaContext is the same as when looked up from a space BandanaContext? (... or do you prefix the key with the space key / a unique global key and a separator ...)

Posted by dhardiker@adaptavist.com at Aug 14, 2006 09:46

No, internally it will work exactly as before, only the storage format has changed.

A space or global scope is represented by the context column. For a space scope, the context value will be the space key; for a global scope, the context value will be SQL NULL.

Posted by mryall at Aug 14, 2006 20:22

Is this the same issue as CONF-6655?

I think someone was looking at it a while back. I'll check on the status, and update the issue if it has changed.

Posted by mryall at Aug 14, 2006 20:34

Yep, same problem. Actually, it's deserialisation that's the problem, not the initial storing of the object. I don't think this will be resolved any time soon - there was a large debate about plugin classloaders which resulted in the current system.

Posted by david@randombits.org at Aug 15, 2006 00:22

Mike and I have both recently looked into the problem, and came to the same conclusion. Essentially that XStream can't be configured enough to solve this problem without forking XStream.

XStream (as far as I can tell) needs to be modified use the classloader of the calling class, so if a plugin is deserializing then that plugin's classloader needs to be used. A temporary solution is to store as JDK classes (or at least classes which are on the webapp's classpath).

Posted by dhardiker@adaptavist.com at Aug 15, 2006 03:22

In David Peterson's example code, the method name is toXML() (upper case XML) and not toXml()! This stumped me for about 15 minutes until I realised that. (The same goes for the fromXML() method later on.)

Posted by chris.cohen at Dec 18, 2006 04:46

Sorry about that - must have been coding from memory

Posted by david@randombits.org at Dec 18, 2006 04:55

I've just started to look at using Bandana in one of my macros/actions (deployed under 2.3 using the embedded database) and noticing that whilst everything seems to work with data being persisted between page views, the moment I shutdown/restart confluence all the data is lost.

This is using "Version: 2.3 Build:#641 $

Unknown macro: {generalUtil.buildDateString}

" (I notice theres alot of missing strings such as the $

being displayed (and elsewhere). Maybe I've just got a broken version or something (thou it was the final release...)

Posted by talios at Jan 21, 2007 18:52

Mark,

Please create a support ticket and describe how you are using bandana in your code. It will also help us if you provided us with the code you are using to store and retrieve values from the bandana.

Cheers,
Dave

Posted by dave@atlassian.com at Jan 24, 2007 20:17
Document generated by Confluence on Mar 22, 2007 21:00