Joda XML integration

Joda's XML integration allows a Java model to be written to XML, and then read back again easily. In this sense, Joda is Java-centric. The integration is not currently designed to take an arbitrary XML model and read it in - DOM should be used for that.

The Joda model is written to XML using SAX. This choice was made because SAX is a single widely accepted API, unlike DOM where there are three or four competing DOM like structures.

Full type conversion is provided between Java objects and their String representations. Joda provides default implementations for all the common Java classes. This mechanism is fully pluggable however, enabling you to add extra conversions for types specific to your application, or to replace the Joda supplied versions.

Inheritance is supported in the XML output. The mechanism used is to write an additional attribute, type, when the type of the bean being output is different from the declared type of the property (ie. when it is a subclass). The type attribute is also always written on the root element of the output XML.

The XML output system will handle recursive references within the beans. If bean A references bean B, that also references bean A, then one or both of the beans must implement the Identifiable interface. This has a single getIdentifier method that is used in the XML process. A standard Joda class Identifiable can be used to generate the identifiers. The identifier will be added as an id attribute of the element representing the bean. When a recursion is detected in the bean hieracrchy, an idref attribute is added to the element representing the bean. Together, these two attributes enable the bean hierarchy to be recreated on XML input.

Lists are output to XML as direct children of the bean element. There is no element added to represent the list property itself. Maps are ouput to XML like lists, but an attribute, key, is added to hold the map's key. The Map key can be of any type that the type convertors can deal with. Thus beans cannot be used as Map keys (but they shouldn't be anyway).

Attributes can be added to Property and Bean objects in the model. These are converted to XML attributes on the relevant output element. Attributes for Lists and Maps are added to the bean element, with the prefix of the list/map name plus a hyphen.

Joda XML string output

1. Create the Joda domain model bean
2. Populate it with data
3. Use XMLOutputter to write the model to a String

Profile profile = (Profile) JodaFactory.create(Profile.class);
profile.person().surname().set("Colebourne");
String str = new XMLOutputter().output(profile, "userProfile");

<userProfile type="org.joda.example.Profile">
 <person>
  <surname>Colebourne</surname>
 </person>
</userProfile>

In this example, a simple object model is created and written to a string. The output is shown, and is nicely formatted. The output can be compressed to remove newline and indents if required by passing true to the XMLOutputter constructor.

Joda SAX output

1. Create the SAX handler, for example the JDOM SAX handler
2. Create the Joda domain model bean
3. Populate it with data
4. Use SAXOutputter to write the model to the SAX handler
5. Get the JDOM document from the SAX handler

org.jdom.input.SAXHandler handler = new org.jdom.input.SAXHandler();
Profile profile = (Profile) JodaFactory.create(Profile.class);
profile.person().surname().set("Colebourne");
String str = new SAXOutputter().output(profile, "userProfile");
org.jdom.Document doc = handler.getDocument();

In this example, a simple object model is created and written to the JDOM SAX handler. The JDOM document created is a normal JDOM object containing the XML version of the Joda model.

Joda SAX input

1. Create the SAX builder
2. Build the Joda domain model bean from the input source, for example an input stream

SAXBuilder builder = new SAXBuilder();
Profile profile = (Profile) builder.build(inputStream);

In this example, the Joda object model written earlier is read back into a bean again. Internally, SAXBuilder uses JAXP to find a parser to parse the XML input into SAX events. Joda also has a SAXHandler that can be passed to external SAXOutputters if required.

Current status

Joda currently supports standard SAX output and input, plus helper classes to write to and read from Strings and Streams. The todo list includes more control over the auto generated attributes, and tools to generate Joda bean classes from DTD/Schema. This may involve refactoring to use Betwixt currently under development at Apache commons.