com.luciad.format.xml.bind.schema

LuciadLightspeedInterface ILcdXMLTypeUnmarshaller<T>

public interface ILcdXMLTypeUnmarshaller<T>

An ILcdXMLTypeUnmarshaller is responsible for unmarshalling (deserializing) XML data into newly created Java content trees. More precisely, a type unmarshaller is responsible for unmarshalling one specific XML Schema type and all of its contents into instances of one (sometimes more) Java class, or, in case of complex data structures, a Java object graph. The XML data are provided via the Streaming API for XML (StAX).

Please refer to the package documentation for a general overview of the XML Binding Framework.

The unmarshalType method from this interface relates to the unmarshal method of the ILcdXMLUnmarshaller interface as follows:

• unmarshal: this method performs the full unmarshalling of one specific XML element. It reads the complete XML element, and unmarshals it into a newly created Java object. If the XML element contains more contents (child elements) than expected, it should throw an XMLStreamException.
• unmarshalType: this method only performs the unmarshalling of the contents of one specific XML schema type. It should only read those attributes and child elements defined by the type, and return at the start tag of the first child element it cannot handle. In contrast to the unmarshal method, it should not throw an XMLStreamException if it encounters more contents (child elements) than expected.

A template for the unmarshalType method

The unmarshalType method should perform the following steps:

• Either cast the specified Object parameter to the expected Java class, or create a new instance if the parameter was null.
• Read all the attributes it can handle, and store them into the Java object.
• Read all the other contents (simple content and/or child elements) it can handle, and store them into the Java object.

Dynamic delegation to the unmarshaller for the XML Schema base type can be used to achieve maximal code reuse. In this case, the unmarshalType method should delegate to the super type's unmarshalType method unmarshaller, between the reading of the attributes and reading of the element's children. The template below illustrates how a typical unmarshalType method, delegating to a super type unmarshaller, should look like:

 public Object unmarshalType( Object aObject, XMLStreamReader aReader, Map aContext ) throws XMLStreamException {
   // Create
   MyObject unmarshalled_object = aObject != null ? (MyObject) aObject: new MyObject();

   // Read this type's attributes using the StAX API.
   unmarshalled_object.setAttributeX(aReader.getAttributeValue("NamespaceURI","AttributeName");
   [...]

   // Delegate to super type unmarshaller.
   super_type_unmarshaller.unmarshalType(unmarshalled_object, aReader, aContext);

   // Read this type's simple contents using the StAX API.
   [...]

   return unmarshalled_object;
 }
 

An important exception to the base type delegation mechanism are XML Schema restrictions; restricted types can be so different from their base type that the base type unmarshaller will no longer be able to read its part of the data correctly. Therefore, restrictions are not expected to delegate to their base type unmarshaller.

See also the ILcdXMLUnmarshaller class documentation for more information about implementing an unmarshaller.

Since:

9.0

Method Summary

Modifier and Type	Method and Description
T	unmarshalType(T aObject, XMLStreamReader aReader, ILcdXMLDocumentContext aContext) Partially unmarshals (deserializes) the XML element at the current cursor position of the specified XMLStreamReader.

Method Detail

unmarshalType

T unmarshalType(T aObject,
                XMLStreamReader aReader,
                ILcdXMLDocumentContext aContext)
         throws XMLStreamException

Partially unmarshals (deserializes) the XML element at the current cursor position of the specified XMLStreamReader.

At the moment this method is called, the cursor should be positioned at the start tag of the element to be unmarshalled. When this method returns, the cursor should be left at the start tag of the first child element (of the element to be unmarshalled) which cannot be handled by this unmarshaller.

The contents of the XML element should be unmarshalled into the object that is passed as parameter.

Parameters:

aObject - the Object to unmarshal the XML element into, or null if this unmarshaller should create a new Java Object itself.

aReader - the StAX reader to unmarshal XML data from.

aContext - a ILcdXMLDocumentContext which can be used to store and retrieve information which is shared between multiple unmarshallers. This context is unique per unmarshalled XML document.

Returns:

aObject, or a newly created Object if aObject was null.

Throws:

XMLStreamException - if any unexpected content occurs within the XML element to be unmarshalled.

ClassCastException - if aObject is not an instance of a class to which this unmarshaller can unmarshal.