com.luciad.format.xml.bind

LuciadLightspeedInterface ILcdXMLMarshaller<T>

All Known Implementing Classes:

TLcdXMLMarshallerAdapter

public interface ILcdXMLMarshaller<T>

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

The following code snippet can be used as a template:

 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. The TLcdXMLMarshallerProvider 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 the ILcdXMLDocumentContext documentation for more information on the use of the document context.

Note on thread-safety

One marshaller instance can be used by a TLcdXMLEncoder to marshal several XML document concurrently. Implementations of this interface should therefore be thread-safe.

Since:

8.2

See Also:

ILcdXMLMarshaller, TLcdXMLUnmarshallerProvider, TLcdXMLDecoder

Method Summary

Modifier and Type	Method and Description
void	marshal(T aObject, XMLStreamWriter aWriter, ILcdXMLDocumentContext aContext) Marshals (serializes) the specified Java object or content tree to an XML element via the specified XMLStreamWriter.

Method Detail

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 specified XMLStreamWriter.

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 - a ILcdXMLDocumentContext 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.