Package com.luciad.format.xml.bind
Interface ILcdXMLMarshaller<T>
- All Known Implementing Classes:
TLcdXMLMarshallerAdapter
public interface ILcdXMLMarshaller<T>
An A template for the
The
ILcdXMLMarshaller
is responsible for marshalling (serializing) Java object graphs into XML data. More
precisely, a marshaller is responsible for marshalling instances of one (sometimes more) Java class, or, in case
of complex data structures, Java object graphs, into one specific XML element. The XML data should be
written via the Streaming API for XML (StAX).
Please refer to the package documentation
for a general overview
of the XML Binding Framework.
A template for the marshal
method
The marshal
method should perform the following steps:
- Write the element's start tag.
- Write all the attributes, and store them into the Java object.
- Write all the other contents (simple content and/or child elements).
- Write the element's end tag.
public void marshal( Object aObject, XMLStreamWriter aWriter, Map aContext ) throws XMLStreamException {
MyObject marshalled_object = (MyObject) aObject;
// Write the element's start tag.
QName name = object.getXMLName();
aWriter.writeStartElement( name.getNamespaceURI(), name.getLocalPart() );
// Marshal the element's attributes.
aWriter.writeAttribute("NamespaceURI", "AttributeName", marshalled_object.getAttributeX());
[...]
// Marshal the element's children.
[...]
// Write the element's end tag.
aWriter.writeEndElement();
}
If the marshaller uses an ILcdXMLTypeMarshaller
for writing its contents,
this can be simplified to the following:
privte ILcdXMLTypeMarshaller fTypeMarshaller;
public void marshal( Object aObject, XMLStreamWriter aWriter, Map aContext ) throws XMLStreamException {
MyObject marshalled_object = (MyObject) aObject;
// Write the element's start tag.
QName name = object.getXMLName();
aWriter.writeStartElement( name.getNamespaceURI(), name.getLocalPart() );
// Marshal the element's contents.
fTypeMarshaller.marshalType( object, aWriter, aContext );
// Write the element's end tag.
aWriter.writeEndElement();
}
Delegating child marshalling to other marshallers
Although it is allowed to write one monolithic marshaller containing not only the code for marshalling a Java object to the corresponding XML element but also all child elements, it is advised to split up the marshalling code and write one marshaller per element. This allows reusage of marshallers (the same element can be a child element of different other elements) and increases the overall readability of the code. TheTLcdXMLMarshallerProvider
class
provides functionality for sharing marshallers.
The following code snippet briefly illustrates how marshalling a child element via delegation to another marshaller
should be done:
private TLcdXMLMarshallerProvider fMarshallerProvider;
public void marshal( Object aMarshalledObject, XMLStreamWriter aWriter, Map aContext ) throws XMLStreamException {
[...]
// Retrieve the child to be marshalled.
MyChild child = aMarshalledObject.getChild();
// Retrieve the marshaller for the child element.
ILcdXMLMarshaller child_marshaller = fMarshallerProvider.getMarshaller( MyConstants.MY_CHILD, MyChild.class );
// Marshal the child.
child_marshaller.marshal( child, aWriter, aContext );
[...]
}
Communication between marshallers
To allow communication between marshallers, the marshalling methods all have a document context argument, which is a Java Map-like interface, in/from which objects can be stored/retrieved. This context is unique per document to be marshalled. Marshallers should document clearly which information they expect to be present in the context Map, and which information they store into the context themselves. See theILcdXMLDocumentContext
documentation for more information on the use of the
document context.
Note on thread-safety
One marshaller instance can be used by aTLcdXMLEncoder
to marshal several XML document
concurrently. Implementations of this interface should therefore be thread-safe.
- Since:
- 8.2
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionvoid
marshal
(T aObject, XMLStreamWriter aWriter, ILcdXMLDocumentContext aContext) Marshals (serializes) the specified Java object or content tree to an XML element via the specifiedXMLStreamWriter
.
-
Method Details
-
marshal
void marshal(T aObject, XMLStreamWriter aWriter, ILcdXMLDocumentContext aContext) throws XMLStreamException Marshals (serializes) the specified Java object or content tree to an XML element via the specifiedXMLStreamWriter
. This method should write a start tag for the object to be marshalled, followed by all the contents (attributes, simple content and child elements) of the object, and end with the corresponding end tag for the object.- Parameters:
aObject
- the object to be marshalled.aWriter
- the XMLStreamWriter to marshal the object to.aContext
- aILcdXMLDocumentContext
which can be used to store and retrieve information which is shared between multiple marshallers. This context is unique per marshalled XML document.- Throws:
XMLStreamException
- if any unexpected content occurs while marshalling the object.- Preconditions:
- The cursor should be positioned at a place where a start tag is allowed.
- Postconditions:
- The cursor should be left at the end tag of the element which was marshalled.
-