public interface ILcdXMLMarshaller<T>
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.
marshal
methodmarshal
method should perform the following steps:
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();
}
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 );
[...]
}
ILcdXMLDocumentContext
documentation for more information on the use of the
document context.
TLcdXMLEncoder
to marshal several XML document
concurrently. Implementations of this interface should therefore be thread-safe.
ILcdXMLMarshaller
,
TLcdXMLUnmarshallerProvider
,
TLcdXMLDecoder
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 . |
void marshal(T aObject, XMLStreamWriter aWriter, ILcdXMLDocumentContext aContext) throws XMLStreamException
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.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.XMLStreamException
- if any unexpected content occurs while marshalling the object.