- Confluence Docs 3.0 : Persistence in Confluence This page last changed on Jun 03, 2008 by dtaylor. There are three main persistence APIs which are used in Confluence: Hibernate - database persistence, difficult to extend. 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. 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: You need to maintain your forked copy of the hibernate mappings file against each new version of Confluence Your new hibernate objects will not be protected from (or necessarily upgraded to) any changes we make in the schema in future versions 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).
  | If you are defining your own type within a plugin, please provide a no argument constructor to avoid class loading issues
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.

Document generated by Confluence on Nov 05, 2009 23:34