Package ucar.unidata.xml

This package provides a set of Xml related classes.

See: Description

Interface Summary

Interface	Description
PreferenceManager	An interface for something that manages preferences.
XmlDelegate	An interface for an object that knows how to handle the xml encoding of certain classes of objects.
XmlObjectFactory	One can define within the encoded object xml the class of an object that implements XmlObjectFactory.
XmlPersistable	An interface that an object that is to be persisted can implement.

Class Summary

Class	Description
ObjectClass	Holds an object (possibly null) and the Class of the object.
XmlDelegateImpl	A siomple implementation of the XmlDelegate interface.
XmlEncoder	See the package.html This class is in part responsible for (de)serializing bundles.
XmlNodeList	A utility that implements the interface NodeList.
XmlObjectStore	This allows us to use the XmlEncoder to read/write a Hashtable that holds a collection of persistent objects.
XmlResourceCollection	An extension of ResourceCollection that handles xml documents.
XmlUtil	A collection of utilities for xml.
XmlUtil.ElementListIterator	_more_

Package ucar.unidata.xml Description

This package provides a set of Xml related classes.

XmlEncoder

The XmlEncoder class supports the serialization/de-serialization of objects to/from xml. It uses reflection on the object to write out an object tag and a set of property or method tags to recreate the object. For primitive types (e.g., int, double) and Strings it writes out special tags: <int>5</int>

Running this class (i.e., java ucar.unidata.xml.XmlEncoder) standalone will run a test. Providing any command line argument will result in the test xml being printed out to stderr.

You can use the toXml and toObject methods to do serialization.

For example, the result of:

String s = "just a test";
XmlEncoder encoder = new XmlEncoder ();
String xml = encoder.toXml (s);

Will be an xml string:

<string>just a test</string>

Now, calling:

Object result = encoder.toObject (xml);

Will result in the String "just a test"

For the class:

public class Test {
   public Test () {}
   public int getX () {...}
   public void setX (int x) {...}
}

The result xml file will be:

<object class="Test">
   <property name="x">
      <int>...</int>
   </property>
</object>

We do special handling for List and Hashtable. In these cases we write out a set of method tags. e.g. for an ArrayList of Strings we do:

<object class="java.util.ArrayList">
   <method name="add">
       <string>Foo</string>
    </method>
   <method name="add">
      <string>Bar</string>
    </method>
</object>

First, the new object (i.e., the ArrayList) is created. Then for each contained method tag the method is looked up (via reflection), the object (or objects) contained by the method tag are instantiated and the method is invoked on the initial object with the newly created object arguments.

XmlPersistable
If the object implements XmlPersistable the encoder will defer to it both when persisting the object and when re-instantiating the object. See Test2.java for an example.

XmlDelegate
Second, you can define an XmlDelegate object that handles objects of a certain class: See Test.java for an example.

encoder.addDelegateForClass (theClassToHandle, theXmlDelegate);

Object factory
Normally the encoding results in a set of nested object tags that contain method and property tags. You can also write out a factory tag that specifies a factory class, which implements XmlObjectFactory. e.g:

<factory class="Test2Factory">
     ...anything here
</factory>

In this case the factory is instantiated but the actual object used is a result of:

Object = factory.getObject (encoder, xml Element);

Constructor tags
Normally, the encoder instantiates an object through reflection using the "bean" (i.e., parameter-less) constructor. For objects that do not have the bean constructor this presents a problem. To resolve this a constructor tag is looked for under the object tag. If found the correct construcor is found for the given class (using the types of the sub-components of the constructor tag. e.g., for Test2 we do:

       <object class="ucar.unidata.xml.Test2">
            <constructor>
              <int>myX</int>
            </constructor>
       </object>