Skip navigation links
LuciadLightspeed
2020.0.14

Package com.luciad.format.xml.bind

Provides a binding framework for binding XML documents to Java object graphs and vice versa.

See: Description

Package com.luciad.format.xml.bind Description

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:

By nesting unmarshallers or marshallers, a framework can be set up to handle very complex XML document structures or large Java object graphs.

Unmarshalling

Overview

Implementing and configuring a simple unmarshalling process involves the following steps:
ILcdXMLUnmarshaller
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.
TLcdXMLUnmarshallerProvider
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.

TLcdXMLDecoder
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.
ILcdXMLDecoderLibrary
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.

Marshalling

Overview

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: 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.

Since:
8.2
Skip navigation links
LuciadLightspeed
2020.0.14