Package com.luciad.format.xml.bind

package com.luciad.format.xml.bind
Provides a binding framework for binding XML documents to Java object graphs and vice versa. The framework in this package is independent from the older XML framework provided by the com.luciad.format.xml and com.luciad.format.xml.schema packages. It is advised to use the framework in this package for new projects.

Binding XML elements to Java classes

The XML binding framework allows to convert XML documents into Java object graphs and vice versa. Creating a Java object graph from an XML document is called unmarshalling, the other way around is called marshalling.

The basic building blocks of the binding framework are unmarshallers and marshallers. An unmarshaller or marshaller is always written for a combination of an XML element and a Java class:

  • In case of an unmarshaller, the unmarshaller can unmarshal instances of a specific XML element into instances of a specific Java class.
  • In case of a marshaller, the marshaller can marshal instances of a specific Java class into instances of a specific XML element.
By nesting unmarshallers or marshallers, a framework can be set up to handle very complex XML document structures or large Java object graphs.



Implementing and configuring a simple unmarshalling process involves the following steps:
The ILcdXMLUnmarshaller is the core interface for XML unmarshalling. Implementations of this interface are responsible for unmarshalling (deserializing) XML data into newly created Java object graphs. The actual parsing of the XML content is done via a StAX XMLStreamReader which is passed to the unmarshaller. Typically, an unmarshaller is capable of unmarshalling instances of one specific XML element into instances of one specific Java class. See the class documentation of ILcdXMLUnmarshaller for more information on how to implement a basic unmarshaller.
In order to achieve maximal code reuse, the programmer should avoid writing monolithic unmarshallers that read large blocks of XML data. Instead, the unmarshalling process should preferably be split up in a set of small unmarshallers, each capable of unmarshalling one specific XML element, delegating the unmarshalling of their child elements to other unmarshallers. The TLcdXMLUnmarshallerProvider acts as the central repository on which unmarshallers for all supported elements should be registered; unmarshallers can then query the unmarshaller provider to retrieve unmarshallers for each of their children.

As the order in which unmarshallers are registered on the unmarshaller provider is unspecified, it cannot be garantueed that unmarshallers for child elements are available already at the moment an unmarshaller is created. Unmarshallers should therefore only retrieve child unmarshallers from the unmarshaller provider from within their unmarshal methods, not from within their constructor.

The TLcdXMLDecoder is the main decoder class from which the unmarshalling process is initiated. It has a TLcdXMLUnmarshallerProvider which provides the decoder with the necessary unmarshallers. It takes care of setting up an input stream and XMLStreamWriter, looking up an unmarshaller for the XML document's root element in the TLcdXMLUnmarshallerProvider and delegates the unmarshalling process to this unmarshaller.
The ILcdXMLDecoderLibrary allows to group unmarshallers into larger building blocks. A decoder library is responsible for instantiating all of its unmarshallers and configure them on the unmarshaller provider of the XML decoder. Libraries are the main API building blocks for distributing sets of unmarshallers; they remove the need to put all individual unmarshaller classes in a public API. To support large and complex XML document hierarchies, multiple libraries can be combined and configured together on a single XML decoder.



Implementing and configuring a simple marshalling process involves the following steps: The main marshaller API classes, ILcdXMLMarshaller, TLcdXMLMarshallerProvider, TLcdXMLEncoder and ILcdXMLMarshallerLibary are similar in use to their unmarshaller counterparts.

Exporting classes via the TLcdXMLJavaClassResolver
In a typical XML-to-Java binding, there is a one-on-one mapping between XML elements and Java classes. In the XML binding framework, this means that a marshaller is normally registered for a specific XML element and specific Java class. There are cases in which this mechanism is not powerful enough, however:
  • Users of a Java domain model might want to extend a class to add some functionality, but map the extension class on the same XML element as its super class. This would require to register the marshaller for all extension classes as well, which is not always possible (it might be unknown at the moment an XML library is written which extensions will be made in the future).
  • Users might want to bind an XML element to a Java interface, instead of a class. This becomes complex however when a class implements multiple interfaces: to which interface should the class be bound?
The TLcdXMLEncoder has a TLcdXMLJavaClassResolver which provides functionality for mapping a Java class to another class or an interface. Whenever no marshaller is found for the class to be marshalled, this resolver will make a list of all Java classes/interfaces this class extends or implements, and choose one of them to bind against, based on a priority list. This allows to register marshallers on the marshaller provider for super classes or interfaces only, and let the class resolver take care of the mapping of derived classes to one of these base classes/interfaces.

  • Class
    The use of this class has been deprecated.
    Interface for XML decoder libraries, responsible for configuring a TLcdXMLDecoder so that it can be used for unmarshalling XML documents to Java object graphs.
    Interface for accessing the context of an XML document being decoded.
    A type-safe enumeration, representing all possible scopes to be used in XML document contexts.
    Contains XML-related information specific to a single XML element.
    Interface for XML encoder libraries, responsible for configuring a TLcdXMLEncoder so that it can be used for marshalling Java object graphs to XML documents.
    Interface for XML mapping libraries, responsible for configuring a TLcdXMLMapping.
    An ILcdXMLMarshaller is responsible for marshalling (serializing) Java object graphs into XML data.
    Interface for object factories that can create objects for a specific XML Schema type or element.
    It separates the creation of objects from the XML parsing and object initialization.
    An ILcdXMLUnmarshaller is responsible for unmarshalling (deserializing) XML data into newly created Java content trees.
    Main class for unmarshalling an XML document into a Java object graph, using ILcdXMLUnmarshaller's.
    Utility class for marshalling Java object graphs into XML documents, using ILcdXMLMarshaller's.
    An XML configuration class which is used by the XML binding framework to decide for which interface or super class of a class a marshaller will be searched, in case no marshaller is available for the class itself.
    Contains a set of object factories that can be used to create a Java instance representing an element from the XML document.
    Provider of ILcdXMLMarshaller's that can marshal instances of a specified Java class to a specified XML element.
    Provider of ILcdXMLObjectFactory's that can create a Java object for a specified XML element.
    Provider of ILcdXMLUnmarshaller's that can unmarshal a specified XML element to instances of a specified Java class.
    This class provides two additional constants that can be used when working with XPathExpression instances working on Luciad domain objects.