Section: 5.7.0 IDV Persistence with XmlEncoder

5.7.0 IDV Persistence with XmlEncoder

The IDV provides a Java object persistence mechanism.

The persistence mechanism is used to save bundles, colortables, station models, etc. The persistence is done with the ucar.unidata.xml.XmlEncoder class. The IDV creates the XmlEncoder with the:

    protected XmlEncoder getEncoder(boolean forRead) {...}

method. If you extend the IntegratedDataViewer class you could override this method to initialize the XmlEncoder differently.

If you create new classes that will be persisted there are some conventions your class needs to follow.

See an example bundle file here: example.xidv

A public parameterless constructor - the "bean" constructor.

Any attributes that are to be saved have public setters/getters of the form:

public void set<Parameter Name>(type param)
public type get<Parameter Name>()

The XmlEncoder will look at and encode non-static public members so its a good idea not to have any.
The parameter types can be most anything, primitive, arrays, lists, hashtables or an object of a class that is also persistable. While public static inner classes are handled, non-static inner classes will no be persistable.
If an object is not persistable the XmlEncoder prints a warning and tries to degrade gracefully.
Once we make a release of the IDV we try very (very, very) hard to always have new changes to classes be backwards compatible with any encoded version of the class. Bundles that were written 4 years can still (for the most part) be read back into the IDV.
Though we have a mechanism to handle class package and name changes we try not to do this. If a public set method is removed (or the type is changed) the encoder flags that as a warning. If you want to remove or change an attribute you need to keep around the old set method and handle the value appropriately.

XmlDelegate

For classes that cannot follow the above conventions one can define a XmlDelegate for the class that handles the persistence for objects of that class.

public interface XmlDelegate {
    /**
     *  Create the xml element for the given object.
     *
     *  @param encoder The XmlEncoder that is calling this method.
     *  @param object The Object to encode.
     *  @return The xml element that defines the given object.
     */
    public Element createElement(XmlEncoder encoder, Object object);

    /**
     *  Create the Object defined by the given xml element.
     *  @param encoder The XmlEncoder that is calling this method.
     *  @param element The xml that defines the object.
     *  @return The Object defined by the xml.
     */
    public Object createObject(XmlEncoder encoder, Element element);
}

Most of the uses of this interface are derived from the XmlDelegateImpl which provides a default createObject method. The delegates overwrite createElement typically by putting on a constructor tag. For example, here we have a delegate that handles the persistence of Color objects:

XmlDelegate xmlDelegate =  new XmlDelegateImpl() {
         public Element createElement(XmlEncoder e, Object o) {
             Color color = (Color) o;
             List args = Misc.newList(new Integer(color.getRed()),
                                      new Integer(color.getGreen()),
                                      new Integer(color.getBlue()));
             List types = Misc.newList(Integer.TYPE, Integer.TYPE,
                                          Integer.TYPE);
             return e.createObjectConstructorElement(o, args, types);
         }
    });

The utility method

XmlEncoder.createObjectConstructorElement(Object o, List args, List types);

creates a constructor tag e.g.:

           <object class="java.awt.Color">
               <constructor>
                  <int>0</int>
                  <int>0</int>
                  <int>0</int>
               </constructor>
          </object>

To add a delegate to an XmlEncoder call:

XmlEncoder.addDelegateForClass(Class theClass, XmlDelegate xmlDelegate);

The XmlEncoder that the IDV uses is initialized with its own addDefaultDelegates() and with the ucar.visad.VisADPersistence.init(XmlEncoder encoder) method.

Right now there is now way to add delegates through a plugin.

XmlPersistable

A class can also implement the interface XmlPersistable and handle its own persistence:

public interface XmlPersistable {
    /**
     *  Create the xml representation of the object.
     *
     *  @param encoder The encoder.
     *  @return The xml representation.
     */
    public Element createElement(XmlEncoder encoder);


    /**
     *  Initialize this object from the given xml element.
     *  @param encoder The encoder.
     *  @param element The xml element representing this object.
     *  @return Return  true if it is ok to do the default processing for this node.
     */
    public boolean initFromXml(XmlEncoder encoder, Element element);
}

In this case it still needs a parameter-less constructor but it will handle its own persistence.

Unidata IDV Workshop for version 6.3 > Java Developer Topics > Miscellaneous