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

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

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