Developer Manual: XML Encoding

This page describes how modelGUI objects are encoded in XML format, and provides some examples on how to utilize this utility. XML encoding confers a number of advantages:

• Persistence of workspaces and their contents across sessions
• Archiving and sharing of workspaces and their contents
• The ability to share modelGUI objects with other applications
• Internet-friendliness :)

Classes which implement or specify the implementation of mgui's XML functionality are contained within packages named "xml". The core classes are contained in the package mgui.interfaces.xml:

InterfaceXMLObject

Java interface which specifies a number of functions that must be implemented by an XML-encodable object; see below.

XMLException

An Exception instance for any errors encountered while loading or writing to XML storage.

XMLFunctions

A utility class which provides a number of string and other functions specific to XML functions.

The class of most interest here is InterfaceXMLObject, which specifies the interface that allows objects to read and write themselves. The functions it specifies are:

getDTD()

Returns a Document Type Definition which specifies the structure of the XML for the particular interface object. The source XML document must be well-formed with respect to this DTD (if it is defined).

getXMLSchema()

Returns an XML schema, which is a more flexible way of defining an XML document type.

getXML(), getXML(int tab)

Returns an XML representation of this object. The tab parameter specifies the starting indent for the XML text, which is useful for embedding objects within other objects. It is notable that, for very large objects, or sets which contain many objects, this method is not ideal; instead, the writeXML method should be used (see below).

handleXMLElementStart(String localName, Attributes attributes), handleXMLElementEnd(String localName), handleXMLString(String s)

Java's built-in SQL functionality is an event-driven implementation, meaning that data is loaded in element parts and sent to an interface object as discrete events. These three methods allow an object to handle these element loading events.

writeXML(int tab, Writer writer), writeXML(int tab, Writer writer, ProgressUpdater updater)

These methods can be used to write an interface object directly into an XML document, by calling writer.write(). Thus, the developer has two options; either fetch the SQL as a String through the getXML functions and write it to the XML document, or write the data directly. For larger objects, or large sets of objects, the latter is necessary.

getShortXML()

If it is not necessary to store an object in its entirety (but only enough data to reference it), this method can be used to provide a short, concise XML representation.