public interface ILcdXMLTypeUnmarshaller<T>
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.
unmarshalType
methodunmarshalType
method should perform the following steps:
null
.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 theILcdXMLUnmarshaller
class documentation for more
information about implementing an unmarshaller.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 . |
T unmarshalType(T aObject, XMLStreamReader aReader, ILcdXMLDocumentContext aContext) throws XMLStreamException
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.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.aObject
, or a newly created Object if aObject
was null
.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.