This page last changed on Nov 08, 2010 by simboss.

One of the most important aspects of the configuration system is persistence. How instances of the configuration are stored to and from disk between GeoServer instances.

XML Peristence with XStream

Currently in GeoServer configuration is persisted as a number of XML files and the entire configuration model is stored in memory. While this implementation strategy has trouble scaling, it is useful as it is simple to setup and easy to provide out of the box. The XStream library provides support for serializing plain old java objects to and from XML.

The configuration model is comprised of simple java beans, which lend themselves easily to be persisted with this strategy. Using the xstream library persisting is as easy as:

// get reference to catalog
Catalog catalog = ...;

//initialize stream
XStream xstream = new XStream();

//write out
xstream.toXML( catalog, new FileOutputStream( ... ) );

And similarly loading from persistence is as easy as:

//initialize stream
XStream xstream = new XStream();

//read in
Catalog catalog = (Catalog) xstream.fromXML( catalog, new FileInputStream( ... ) );

A working example is available in the prototype section.

Backward Compatibility

An important question to ask is how xstream will deal with changes to configuration model classes. In particular:

Addition of a Field

Addition is handled transparently by stream, the field that was added in the new version of a class is simply ignored and its value will be uninitialized, or initialized to the system default for primitive types.

Removal of a Field

Removal of a field causes an exception when xstream encounters a persisted value which does not map to a field of a class. The simplest way to deal with this case is too not remove the field, simply deprecate it, and mark it as transient if necessary to prevent it from being included in subsequent serialization.

A more advanced option is to register a custom "xstream converter", which will handle the marshalling and unmarshalling of the object which the field has been removed from.

Modification of the type of a Field

When xstream reads a field value from xml, it uses the class of the field and tries its best to convert the value into an instance of the field type. In some cases it will be possible to change the type of a field and xstream will seemlessly convert, for example changing the type of a field from Integer to String. However often no conversion will fail, like changing the type of a field from String to Integer.

So in this case, similar to removal, we can either deprecate the old field, and add a new one, or register a custom converter. In this case the custom converter option is more attractive as it is possible to register the converter against the class of the field, and not the class of which the field is a part of.

As an example for the case of String to Integer we could register the converter which tries the normal conversion, but catches the failure and simply leaves the field initialized.

Relational Database Persistence with Hibernate

Please review the prototype for an example of backing this api onto hibernate. The goal here is to show GeoServer configuration being delegated to a central database; allowing deployment in a cluster.

Document generated by Confluence on May 14, 2014 23:00