Marshaller and Unmarshaller

Marshaller and Unmarshaller
Prev	Chapter 5. Marshalling XML using O/X Mappers	Next

As stated in the introduction, a marshaller serializes an object to XML, and an unmarshaller deserializes XML stream to an object. In this section, we will describe the two Spring interfaces used for this purpose.

Marshaller

Spring abstracts all marshalling operations behind the org.springframework.oxm.Marshaller interface, which is listed below.

public interface Marshaller {

    /**
     * Marshals the object graph with the given root into the provided Result.
     */
    void marshal(Object graph, Result result)
        throws XmlMappingException, IOException;
}

The Marshaller interface has just one method, which marshals the given object to a given javax.xml.transform.Result . Result is a tagging interface that basically represents an XML output abstraction: concrete implementations wrap various XML representations, as indicated in the table below.

`javax.xml.transform.Result` implementation	Wraps XML representation
`javax.xml.transform.dom.DOMResult`	`org.w3c.dom.Node`
`javax.xml.transform.sax.SAXResult`	`org.xml.sax.ContentHandler`
`javax.xml.transform.stream.StreamResult`	`java.io.File` , `java.io.OutputStream` , or `java.io.Writer`

Note

Although the marshal method accepts a plain object as its first parameter, most Marshaller implementations cannot handle arbitrary objects. Instead, an object class must be mapped in a mapping file, registered with the marshaller, or have a common base class. Refer to the further sections in this chapter to determine how your O/X technology of choice manages this.

Unmarshaller

Similar to the Marshaller , there is the org.springframework.oxm.Unmarshaller interface.

public interface Unmarshaller {

    /**
     * Unmarshals the given provided Source into an object graph.
     */
    Object unmarshal(Source source)
        throws XmlMappingException, IOException;
}

This interface also has one method, which reads from the given javax.xml.transform.Source (an XML input abstraction), and returns the object read. As with Result, Source is a tagging interface that has three concrete implementations. Each wraps a different XML representation, as indicated in the table below.

`javax.xml.transform.Source` implementation	Wraps XML representation
`javax.xml.transform.dom.DOMSource`	`org.w3c.dom.Node`
`javax.xml.transform.sax.SAXSource`	`org.xml.sax.InputSource` and `org.xml.sax.XMLReader`
`javax.xml.transform.stream.StreamSource`	`java.io.File` , `java.io.InputStream` , or `java.io.Reader`

Even though there are two separate marshalling interfaces ( Marshaller and Unmarshaller ), most implementations found in Spring-WS implement both in one class. This means that you can wire up one marshaller class and refer to it as marshaller and unmarshaller in your applicationContext.xml .

XmlMappingException

Spring converts exceptions from the underlying O/X mapping tool to its own exception hierarchy with the XmlMappingException as the root exception. As can be expected, these runtime exceptions wrap the original exception so no information will be lost.

Additionally, the MarshallingFailureException and UnmarshallingFailureException provide a distinction between marshalling and unmarshalling operations, even though the underlying O/X mapping tool does not do so.

The O/X Mapping exception hierarchy is shown in the following figure:

O/X Mapping exception hierarchy