X-O lite usage

This document explains how to use java objects implementing the XmlSerializable interface of X-O lite to parse or generate XML documents (or in other terms serialize/deserialize or marshall/unmarshall your objects to/from XML). It also explains how XmlSerializable objects integrates with other XML-related API like DOM or XSLT.

The way make your objects implementing XMLSerializable interface is explained in the 'XMLSerializable Implementation' document.

prerequisites: Though X-O lite is based on SAX, this document will not re-explain the SAX (Simple API for XML) usage. To know more about SAX itself, go to http://en.wikipedia.org/wiki/Simple_API_for_XML or http://www.saxproject.org/.

Usage overview

To parse = create your java objects from another XML representation (usually a XML file) you use an XMLEventParser matching the type of source you have.

To serialize your java objects = create a standard XML representation (usually a XML file) you use an XMLSerializer matching the the type of target you want to produce.

Of course, your XMLSerializable objects only see the XMLEventParser and XMLSerializer interfaces, so they can be used with any kind of source and target.

The available XMLEventParser are:

  • SaxXMLEventParser : To parse all input that can be processed by a SAX parser. This class can create and configure the SAX parser automatically.
  • DomXMLEventParser : To create your java objects from a DOM document.
  • XMLEventParserResult : This class implements the XSLT Result interface so it can be used to create XMLSerializable objects directly from an XSLT transformer output. This class doesn't implement XMLEventParser directly but uses internally an XMLEventParser to interpret the XSLT output.

The available XMLSerializer are:

  • StreamXMLSerializer : To write the objects as XML in an output stream.
  • DomXMLSerializer : To create a DOM document from your objects.
  • SaxXMLSerializer : To generate SAX event from your java objects (just as if the corresponding XML is read from a file by a SaxReader). The event generated can be consumed by any implementation of SAX DocumentHandler.
  • ConsoleXMLSerializer : To dump the objects as XML to the java console (useful for log or debug).
  • StringXMLSerializer : To create a String containing serialized XML. This is rarely needed, StreamXMLSerializer is a better solution in most of the cases. Using Strings to store XML can lead to performance problems and encoding problems.
  • XMLSerializableSource : This class implements the XSLT Source interface. It allows using XMLSerializable objects directly as XSLT transformer input. The XMLSerializableSource class doesn't implement XMLSerializer directly but uses internally an XMLSerializer to generate the XSLT input.