com.luciad.format.xml.bind.schema (LuciadLightspeed API documentation)

Interface Summary
Interface	Description
ILcdXMLDatatypeMarshaller<T>	Converts instances of a Java class to lexical representations of their corresponding XML value of the XML Schema datatype for which this formatter was written.
ILcdXMLDatatypeUnmarshaller<T>	Converts lexical representations of XML values of the XML Schema datatype for which this parser was written to corresponding Java class instances representing these values.
ILcdXMLSchemaBasedDecoderLibrary	Interface for XML Schema based decoder libraries, responsible for configuring a `TLcdXMLDecoder` so that it can be used for unmarshalling XML documents to Java object graphs.
ILcdXMLSchemaBasedEncoderLibrary	Interface for XML Schema based encoder libraries, responsible for configuring a `TLcdXMLSchemaBasedEncoder` so that it can be used for marshalling Java object graphs to XML documents.
ILcdXMLSchemaBasedMappingLibrary	Interface for XML Schema mapping libraries, responsible for configuring a `TLcdXMLSchemaBasedMapping`.
ILcdXMLSchemaHandler	Interface for handlers of XML Schemas.
ILcdXMLTypeMarshaller<T>	An `ILcdXMLTypeMarshaller` is responsible for marshalling (serializing) Java object graphs into XML data.
ILcdXMLTypeUnmarshaller<T>	An `ILcdXMLTypeUnmarshaller` is responsible for unmarshalling (deserializing) XML data into newly created Java content trees.

Class Summary
Class	Description
ALcdXMLModelDecoder	`ILcdModelDecoder` that provides additional infrastructure to decode XML schema based documents.
ALcdXMLModelEncoder	This abstract class provides additional methods for a `ILcdModelEncoder` to encode models into XML schema based documents.
TLcdXMLBuiltInConstants	This class groups a number of classes defining public constants for the http://www.w3.org/2001/XMLSchema schema.
TLcdXMLBuiltInConstants.XSD	This class groups a number of classes defining public constants for the http://www.w3.org/2001/XMLSchema schema.
TLcdXMLBuiltInConstants.XSD.Name	This class provides easy access to all XML names of the http://www.w3.org/2001/XMLSchema schema.
TLcdXMLBuiltInConstants.XSD.Type	This class provides easy access to all XML types defined in the http://www.w3.org/2001/XMLSchema schema.
TLcdXMLBuiltInDatatypeConverter	Utility class providing static methods for converting XML lexical values to Java representations and vice versa.
TLcdXMLBuiltInDataTypes	This class provides access to the data model and the types of XML schema (http://www.w3.org/2001/XMLSchema).
TLcdXMLBuiltInDecoderLibrary	Implementation of `ILcdXMLSchemaBasedDecoderLibrary` for the XML base Schema.
TLcdXMLBuiltInEncoderLibrary	Implementation of `ILcdXMLSchemaBasedEncoderLibrary` for the XML base Schema.
TLcdXMLBuiltInMappingLibrary	Implementation of `ILcdXMLSchemaBasedMappingLibrary` for the XML base Schema (http://www.w3.org/2001/XMLSchema).
TLcdXMLFeaturedDescriptor	Implementation of `com.luciad.util.ILcdCollectionFeaturedDescriptor` that contains additional XML-related information about the object it describes.
TLcdXMLFeaturedObject	Default implementation for XML domain objects, based on `ILcdSelfDescribedFeatured`.
TLcdXMLMarshallerAdapter<T>	A wrapper class for `ILcdXMLTypeMarshaller` that converts it into an `ILcdXMLMarshaller`.
TLcdXMLSchemaBasedDecoder	Decoder for decoding an XML Schema-based XML document into a Java object graph, using `ILcdXMLUnmarshaller`'s and `ILcdXMLTypeUnmarshaller`'s.
TLcdXMLSchemaBasedEncoder	Encoder for marshalling a Java object graph into an XML Schema-based XML document, using `ILcdXMLMarshaller`'s and `ILcdXMLTypeMarshaller`'s.
TLcdXMLSchemaBasedMapping	Contains information common to XML decoders and encoders.
TLcdXMLSchemaBasedMappingUtil	Provides utility methods for working with XML Schema mappings.
TLcdXMLSchemaBasedMarshallerProvider	Extended `TLcdXMLMarshallerProvider` that creates marshallers on-the-fly using a `TLcdXMLSchemaBasedEncoder`'s type marshaller provider.
TLcdXMLSchemaBasedUnmarshallerProvider	Extended `TLcdXMLUnmarshallerProvider` that also allows unmarshallers to be `registered` and retrieved for local elements.
TLcdXMLSchemaElement	Represents an element declaration in an XML Schema.
TLcdXMLSchemaElementIdentifier	An identifier for XML schema elements.
TLcdXMLSchemaSet	Container of XML Schema information which is used by the XML Binding Framework.
TLcdXMLSchemaType	Represents a type declaration in an XML Schema.
TLcdXMLSchemaTypeIdentifier	An identifier for XML schema types that allows referring to both global and anonymous types.
TLcdXMLSchemaTypeIdentifier.Builder	Builder to easily add steps to create schema type identifiers.
TLcdXMLTypeMarshallerProvider	Provider of `ILcdXMLTypeMarshaller`'s and `ILcdXMLSchemaDatatypeMarshaller`'s that can marshal instances of a specified Java class to instances of an XML element with a specified XML Schema type or datatype.
TLcdXMLTypeObjectFactoryProvider	Provider of `com.luciad.format.xml.bind.schema.ILcdXMLSchemaObjectFactory`'s that can create Java instances for XML types and datatypes.
TLcdXMLTypeUnmarshallerProvider	Provider of `ILcdXMLTypeUnmarshaller`'s and `ILcdXMLSchemaDatatypeUnmarshaller`'s that can unmarshal a specified XML Schema type or datatype to instances of a specified Java class.
TLcdXMLUnmarshallerAdapter<T>	A wrapper class for `ILcdXMLTypeUnmarshaller` that converts it into an `ILcdXMLUnmarshaller`.

Enum Summary
Enum Description

TLcdXMLSchemaTypeIdentifier.StepAxis
The semantic meaning of a schema type identifier step (e.g. an attribute, an element group, a union).

Enum Summary
Enum	Description
TLcdXMLSchemaTypeIdentifier.StepAxis	The semantic meaning of a schema type identifier step (e.g. an attribute, an element group, a union).

Package com.luciad.format.xml.bind.schema Description

Provides an extension to the XML runtime binding framework com.luciad.format.xml.bind for XML Schema based documents.

XML Schema adds extra power on top of XML; to fully exploit the features of XML Schema, additional classes are provided by the XML binding framework.

Unmarshalling

The TLcdXMLSchemaBasedDecoder is responsible for decoding XML documents. Once it has been configured with one or more data models, it can decode XML documents into the Java domain classes defined by the data models. The decoding process is highly configurable. The decoder supports an input stream factory, a XML reader factory and (via its mapping) an entity resolver. These objects allow the application to control how the decoder gets its input (both document and schema). In addition, the XML framework allows application-specific decoding of XML elements or types.

ILcdXMLTypeUnmarshaller

While ILcdXMLUnmarshaller is responsible for decoding XML elements, ILcdXMLTypeUnmarshaller is responsible for decoding XML Schema types. The ILcdXMLTypeUnmarshaller interface allows to chain a set of schema type unmarshallers corresponding to the XML Schema type hierarchy, each type unmarshaller responsible for unmarshalling only those attributes and child elements which are defined in the corresponding type. See the documentation of the ILcdXMLTypeUnmarshaller for detailed information on how to write XML Schema type unmarshallers.

ILcdXMLSchemaDatatypeUnmarshaller

XML Schema defines a set of built-in datatypes. In addition, schemas can derive their own types from this set of built-in types. Datatypes are used to define the value space of attributes or the simple content of elements. The ILcdXMLDatatypeUnmarshaller interface should be implemented by all unmarshallers for datatypes.

TLcdXMLSchemaTypeUnmarshallerProvider

Elements of one XML schema might have a type which is defined in another schema. In order to be able to share and reuse type unmarshallers among decoder libraries for different XML schemas, it should be possible to share type unmarshallers based on their XML Schema type, instead of XML element. The TLcdXMLTypeUnmarshallerProvider is a repository on which type unmarshallers for XML Schema types and datatypes can be registered.

TLcdXMLSchemaSet

XML schemas contain information about elements and types. Parts of the schema are needed by the framework to take full advantage of XML schema. This information is stored in the TLcdXMLSchemaSet class.

ILcdXMLSchemaBasedDecoderLibrary

The ILcdXMLSchemaBasedDecoderLibrary bundles all information associated with a set of XML unmarshallers for a given XML schema in a single class. Typically, a library is written for each XML schema. A decoder can be instantiated by creating a set of library instances, one for each of the schemas that are used, and passing this set to the constructor of the decoder; the decoder will automatically configure itself by calling one-by-one each of the registration methods for each of the libraries.

Mapping XML substitution groups onto Java class hierarchies

XML Schema provides a mechanism, called substitution groups, that allows elements to be substituted for other elements.

Although one is free to use an arbitrary mapping between XML Schema and Java domain model, the following approach offers maximal extensibility and handles substitution groups in a very natural way:

On the Java domain model level, a substitution group can be modeled as a class hierarchy, where the substitution head is mapped on the root class of the class hierarchy, and the substitutes are mapped on extensions of this class. Alternatively, the substitution head can be mapped on an interface, in which case the substitutes should be mapped on classes implementing this interface.
Whenever an unmarshaller for a given [XML element, Java class] pair is retrieved from the unmarshaller provider, the unmarshaller provider will look for an unmarshaller that is capable of unmarshalling the specified XML element to an instance of the specified Java class, or to an instance of a class which is assignable to the specified class. If the substitution group is properly modeled as a class hierarchy, as described in the previous point, unmarshalling a substitutable child element can then be done as follows:
```
 // Retrieve the unmarshaller for the child element.
 ILcdXMLUnmarshaller<HeadClass> child_unmarshaller = fUnmarshallerProvider.getUnmarshaller( aReader.getName(), HeadClass.class );
 // Unmarshal the child.
 HeadClass child = child_unmarshaller.unmarshal( aReader, aContext );
 
```
The advantage of this approach is that the parent unmarshaller does not have to know anything about the substitutes of the child element, which means that extending the substitution group with a new element can simply be done by registering the unmarshaller for the new element on the unmarshaller provider, without having to modify the parent unmarshaller's code.

Marshalling

The main XML Schema marshaller API classes, TLcdXMLSchemaBasedEncoder, ILcdXMLTypeMarshaller, ILcdXMLDatatypeMarshaller, TLcdXMLTypeMarshallerProvider, and ILcdXMLSchemaBasedEncoderLibrary are similar in use to their unmarshaller counterparts.

Mapping Java class hierarchies onto XML substitution groups

Java's class extension mechanism allows to assign to a member field of an object, an instance of a subclass of the field's class. Such a subclass might have additional properties and it might be desirable to map this subclass onto another XML element than the XML element onto which the field's class is mapped. The XML Schema substitution group mechanism can be used to handle this Java extension mechanism in a very natural way, as follows:

The XML schema should be designed in such a way that the Java class hierarchy is mapped onto an XML substitution group hierarchy; this means that the original field class is mapped onto the head of a new substitution group and all extension classes are mapped onto elements which are part of this substitution group.
Whenever a marshaller for a given [XML element, Java class] pair is retrieved from the marshaller provider, the marshaller provider will look for a marshaller that is capable of marshalling the specified Java class to an instance of the XML element, or to an instance of an XML element in the substitution group of the specified element. If the Java class hierarchy is properly mapped onto an XML substitution group, as described in the previous point,marshalling a substitutable child object can then be done as follows:
```
 // Retrieve the marshaller for the child element.
 ILcdXMLMarshaller child_marshaller = fMarshallerProvider.getMarshaller( MyConstants.HEAD_ELEMENT, child.getClass() );
 // Marshal the child.
 child_marshaller.marshal( child, aWriter, aContext );
 
```
The advantage of this approach that the parent marshaller does not have to know anything about the substitutes of the child, which means that adding a new Java extension class can simply be done by registering the marshaller for the new class on the marshaller provider, without having to modify the parent marshaller's code.

Schema mapping

Common to both encoder and decoder is the TLcdXMLSchemaBasedMapping. This class is responsible for mapping XML schema types on Java classes. It supports the registration of object factories that can create Java objects for a combination of an XML schema type and a Java class. In addition, the mapping keeps track of the necessary schema information (such as for instance information on XML substitution groups).

Since:: 8.2