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.

Unmarshalling

Overview

Implementing and configuring a simple unmarshalling process involves the following steps:

• Write ILcdXMLUnmarshaller classes for each of the supported XML elements.
• Write an implementation of ILcdXMLDecoderLibrary that instantiates all unmarshallers and registers them on a TLcdXMLUnmarshallerProvider.
• Create a new TLcdXMLDecoder instance with this library.
• Once the decoder is set up, XML documents can be unmarshalled using the decoder's decode method.

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:

• Write ILcdXMLMarshaller classes for each of the supported XML elements.
• Write an implementation of ILcdXMLEncoderLibrary that groups all marshallers and registers them on a TLcdXMLMarshallerProvider.
• Create a new TLcdXMLEncoder instance with this library.
• Once the encoder is set up, Java object graphs can be marshalled using the encoder's encode method.

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.

Since:

8.2

Related Packages

Package	Description
com.luciad.format.xml	Provides a generic framework for parsing of XML documents, using pluggable XML element readers and object factories.
com.luciad.format.xml.bind.schema	Provides an extension to the XML runtime binding framework com.luciad.format.xml.bind for XML Schema based documents.
com.luciad.format.xml.bind.xlink	This package provides support for representing and automatically resolving XLink (http://www.w3.org/TR/xlink/) references during the decoding of a XML model.
com.luciad.format.xml.datatype	Provides Java classes for XML data types.
com.luciad.format.xml.schema	Extension of the XML Framework provided by the com.luciad.format.xml package, offering support for XML Schema-based documents.
com.luciad.format.xml.util	Contains utility functionality for XML.
com.luciad.format.xml.xlink	Provides interfaces modelling the W3C XLink schema (http://www.w3.org/TR/xlink/).
com.luciad.format.xml.xpath	This package provides support for XPath.

Class	Description
ALcdXMLDocumentDescriptor	Deprecated. The use of this class has been deprecated.
ILcdXMLDecoderLibrary	Interface for XML decoder libraries, responsible for configuring a TLcdXMLDecoder so that it can be used for unmarshalling XML documents to Java object graphs.
ILcdXMLDocumentContext	Interface for accessing the context of an XML document being decoded.
ILcdXMLDocumentContext.Scope	A type-safe enumeration, representing all possible scopes to be used in XML document contexts.
ILcdXMLElementInfo	Contains XML-related information specific to a single XML element.
ILcdXMLEncoderLibrary	Interface for XML encoder libraries, responsible for configuring a TLcdXMLEncoder so that it can be used for marshalling Java object graphs to XML documents.
ILcdXMLMappingLibrary	Interface for XML mapping libraries, responsible for configuring a TLcdXMLMapping.
ILcdXMLMarshaller<T>	An ILcdXMLMarshaller is responsible for marshalling (serializing) Java object graphs into XML data.
ILcdXMLObjectFactory<T>	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.
ILcdXMLUnmarshaller<T>	An ILcdXMLUnmarshaller is responsible for unmarshalling (deserializing) XML data into newly created Java content trees.
TLcdXMLDecoder	Main class for unmarshalling an XML document into a Java object graph, using ILcdXMLUnmarshaller's.
TLcdXMLEncoder	Utility class for marshalling Java object graphs into XML documents, using ILcdXMLMarshaller's.
TLcdXMLJavaClassResolver	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.
TLcdXMLMapping	Contains a set of object factories that can be used to create a Java instance representing an element from the XML document.
TLcdXMLMarshallerProvider	Provider of ILcdXMLMarshaller's that can marshal instances of a specified Java class to a specified XML element.
TLcdXMLObjectFactoryProvider	Provider of ILcdXMLObjectFactory's that can create a Java object for a specified XML element.
TLcdXMLUnmarshallerProvider	Provider of ILcdXMLUnmarshaller's that can unmarshal a specified XML element to instances of a specified Java class.
TLcdXMLXPathConstants	This class provides two additional constants that can be used when working with XPathExpression instances working on Luciad domain objects.