AbstractMarshaller (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.oxm.support

## Class AbstractMarshaller

- java.lang.Object
- - org.springframework.oxm.support.AbstractMarshaller

- All Implemented Interfaces:
    Marshaller, Unmarshaller
  Direct Known Subclasses:
    CastorMarshaller, JibxMarshaller, XmlBeansMarshaller, XStreamMarshaller

      public abstract class AbstractMarshaller
      extends Object
      implements Marshaller, Unmarshaller

  Abstract implementation of the `Marshaller` and `Unmarshaller` interface. This implementation inspects the given `Source` or `Result`, and defers further handling to overridable template methods.
  Since:
    3.0
  Author:
    Arjen Poutsma, Juergen Hoeller

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Log` | `logger` Logger available to subclasses.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractMarshaller()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected DocumentBuilder` | `createDocumentBuilder(DocumentBuilderFactory factory)` Create a `DocumentBuilder` that this marshaller will use for creating DOM documents when passed an empty `DOMSource`.
    `protected DocumentBuilderFactory` | `createDocumentBuilderFactory()` Create a `DocumentBuilder` that this marshaller will use for creating DOM documents when passed an empty `DOMSource`.
    `protected XMLReader` | `createXmlReader()` Create a `XMLReader` that this marshaller will when passed an empty `SAXSource`.
    `void` | `marshal(Object graph, Result result)` Marshals the object graph with the given root into the provided `javax.xml.transform.Result`.
    `protected abstract void` | `marshalDomNode(Object graph, Node node)` Abstract template method for marshalling the given object graph to a DOM `Node`.
    `protected void` | `marshalDomResult(Object graph, DOMResult domResult)` Template method for handling `DOMResult`s.
    `protected abstract void` | `marshalOutputStream(Object graph, OutputStream outputStream)` Abstract template method for marshalling the given object graph to a `OutputStream`.
    `protected abstract void` | `marshalSaxHandlers(Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler)` Abstract template method for marshalling the given object graph to a SAX `ContentHandler`.
    `protected void` | `marshalSaxResult(Object graph, SAXResult saxResult)` Template method for handling `SAXResult`s.
    `protected void` | `marshalStaxResult(Object graph, Result staxResult)` Template method for handling `StaxResult`s.
    `protected void` | `marshalStreamResult(Object graph, StreamResult streamResult)` Template method for handling `StreamResult`s.
    `protected abstract void` | `marshalWriter(Object graph, Writer writer)` Abstract template method for marshalling the given object graph to a `Writer`.
    `protected abstract void` | `marshalXmlEventWriter(Object graph, XMLEventWriter eventWriter)` Abstract template method for marshalling the given object to a StAX `XMLEventWriter`.
    `protected abstract void` | `marshalXmlStreamWriter(Object graph, XMLStreamWriter streamWriter)` Abstract template method for marshalling the given object to a StAX `XMLStreamWriter`.
    `Object` | `unmarshal(Source source)` Unmarshals the given provided `javax.xml.transform.Source` into an object graph.
    `protected abstract Object` | `unmarshalDomNode(Node node)` Abstract template method for unmarshalling from a given DOM `Node`.
    `protected Object` | `unmarshalDomSource(DOMSource domSource)` Template method for handling `DOMSource`s.
    `protected abstract Object` | `unmarshalInputStream(InputStream inputStream)` Abstract template method for unmarshalling from a given `InputStream`.
    `protected abstract Object` | `unmarshalReader(Reader reader)` Abstract template method for unmarshalling from a given `Reader`.
    `protected abstract Object` | `unmarshalSaxReader(XMLReader xmlReader, InputSource inputSource)` Abstract template method for unmarshalling using a given SAX `XMLReader` and `InputSource`.
    `protected Object` | `unmarshalSaxSource(SAXSource saxSource)` Template method for handling `SAXSource`s.
    `protected Object` | `unmarshalStaxSource(Source staxSource)` Template method for handling `StaxSource`s.
    `protected Object` | `unmarshalStreamSource(StreamSource streamSource)` Template method for handling `StreamSource`s.
    `protected abstract Object` | `unmarshalXmlEventReader(XMLEventReader eventReader)` Abstract template method for unmarshalling from a given Stax `XMLEventReader`.
    `protected abstract Object` | `unmarshalXmlStreamReader(XMLStreamReader streamReader)` Abstract template method for unmarshalling from a given Stax `XMLStreamReader`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.springframework.oxm.Marshaller

      `supports`

    - ### Methods inherited from interface org.springframework.oxm.Unmarshaller

      `supports`

- - ### Field Detail

    - #### logger

          protected final Log logger

      Logger available to subclasses.

  - ### Constructor Detail

    - #### AbstractMarshaller

          public AbstractMarshaller()

  - ### Method Detail

    - #### marshal

          public final void marshal(Object graph,
                     Result result)
                             throws IOException,
                                    XmlMappingException

      Marshals the object graph with the given root into the provided `javax.xml.transform.Result`.

      This implementation inspects the given result, and calls `marshalDomResult`, `marshalSaxResult`, or `marshalStreamResult`.

      Specified by:
        `marshal` in interface `Marshaller`
      Parameters:
        `graph` - the root of the object graph to marshal
        `result` - the result to marshal to
      Throws:
        `IOException` - if an I/O exception occurs
        `XmlMappingException` - if the given object cannot be marshalled to the result
        `IllegalArgumentException` - if `result` if neither a `DOMResult`, a `SAXResult`, nor a `StreamResult`
      See Also:
        `marshalDomResult(Object, javax.xml.transform.dom.DOMResult)`, `marshalSaxResult(Object, javax.xml.transform.sax.SAXResult)`, `marshalStreamResult(Object, javax.xml.transform.stream.StreamResult)`

    - #### unmarshal

          public final Object unmarshal(Source source)
                                 throws IOException,
                                        XmlMappingException

      Unmarshals the given provided `javax.xml.transform.Source` into an object graph.

      This implementation inspects the given result, and calls `unmarshalDomSource`, `unmarshalSaxSource`, or `unmarshalStreamSource`.

      Specified by:
        `unmarshal` in interface `Unmarshaller`
      Parameters:
        `source` - the source to marshal from
      Returns:
        the object graph
      Throws:
        `IOException` - if an I/O Exception occurs
        `XmlMappingException` - if the given source cannot be mapped to an object
        `IllegalArgumentException` - if `source` is neither a `DOMSource`, a `SAXSource`, nor a `StreamSource`
      See Also:
        `unmarshalDomSource(javax.xml.transform.dom.DOMSource)`, `unmarshalSaxSource(javax.xml.transform.sax.SAXSource)`, `unmarshalStreamSource(javax.xml.transform.stream.StreamSource)`

    - #### createDocumentBuilder

          protected DocumentBuilder createDocumentBuilder(DocumentBuilderFactory factory)
                                                   throws ParserConfigurationException

      Create a `DocumentBuilder` that this marshaller will use for creating DOM documents when passed an empty `DOMSource`.

      Can be overridden in subclasses, adding further initialization of the builder.

      Parameters:
        `factory` - the `DocumentBuilderFactory` that the DocumentBuilder should be created with
      Returns:
        the `DocumentBuilder`
      Throws:
        `ParserConfigurationException` - if thrown by JAXP methods

    - #### createDocumentBuilderFactory

          protected DocumentBuilderFactory createDocumentBuilderFactory()
                                                                 throws ParserConfigurationException

      Create a `DocumentBuilder` that this marshaller will use for creating DOM documents when passed an empty `DOMSource`.

      The resulting `DocumentBuilderFactory` is cached, so this method will only be called once.

      Returns:
        the DocumentBuilderFactory
      Throws:
        `ParserConfigurationException` - if thrown by JAXP methods

    - #### createXmlReader

          protected XMLReader createXmlReader()
                                       throws SAXException

      Create a `XMLReader` that this marshaller will when passed an empty `SAXSource`.
      Returns:
        the XMLReader
      Throws:
        `SAXException` - if thrown by JAXP methods

    - #### marshalDomResult

          protected void marshalDomResult(Object graph,
                              DOMResult domResult)
                                   throws XmlMappingException

      Template method for handling `DOMResult`s.

      This implementation delegates to `marshalDomNode`.

      Parameters:
        `graph` - the root of the object graph to marshal
        `domResult` - the `DOMResult`
      Throws:
        `XmlMappingException` - if the given object cannot be marshalled to the result
        `IllegalArgumentException` - if the `domResult` is empty
      See Also:
        `marshalDomNode(Object, org.w3c.dom.Node)`

    - #### marshalStaxResult

          protected void marshalStaxResult(Object graph,
                               Result staxResult)
                                    throws XmlMappingException

      Template method for handling `StaxResult`s.

      This implementation delegates to `marshalXMLSteamWriter` or `marshalXMLEventConsumer`, depending on what is contained in the `StaxResult`.

      Parameters:
        `graph` - the root of the object graph to marshal
        `staxResult` - a Spring `StaxSource` or JAXP 1.4 `StAXSource`
      Throws:
        `XmlMappingException` - if the given object cannot be marshalled to the result
        `IllegalArgumentException` - if the `domResult` is empty
      See Also:
        `marshalDomNode(Object, org.w3c.dom.Node)`

    - #### marshalSaxResult

          protected void marshalSaxResult(Object graph,
                              SAXResult saxResult)
                                   throws XmlMappingException

      Template method for handling `SAXResult`s.

      This implementation delegates to `marshalSaxHandlers`.

      Parameters:
        `graph` - the root of the object graph to marshal
        `saxResult` - the `SAXResult`
      Throws:
        `XmlMappingException` - if the given object cannot be marshalled to the result
      See Also:
        `marshalSaxHandlers(Object, org.xml.sax.ContentHandler, org.xml.sax.ext.LexicalHandler)`

    - #### marshalStreamResult

          protected void marshalStreamResult(Object graph,
                                 StreamResult streamResult)
                                      throws XmlMappingException,
                                             IOException

      Template method for handling `StreamResult`s.

      This implementation delegates to `marshalOutputStream` or `marshalWriter`, depending on what is contained in the `StreamResult`

      Parameters:
        `graph` - the root of the object graph to marshal
        `streamResult` - the `StreamResult`
      Throws:
        `IOException` - if an I/O Exception occurs
        `XmlMappingException` - if the given object cannot be marshalled to the result
        `IllegalArgumentException` - if `streamResult` does neither contain an `OutputStream` nor a `Writer`

    - #### unmarshalDomSource

          protected Object unmarshalDomSource(DOMSource domSource)
                                       throws XmlMappingException

      Template method for handling `DOMSource`s.

      This implementation delegates to `unmarshalDomNode`. If the given source is empty, an empty source `Document` will be created as a placeholder.

      Parameters:
        `domSource` - the `DOMSource`
      Returns:
        the object graph
      Throws:
        `XmlMappingException` - if the given source cannot be mapped to an object
        `IllegalArgumentException` - if the `domSource` is empty
      See Also:
        `unmarshalDomNode(org.w3c.dom.Node)`

    - #### unmarshalStaxSource

          protected Object unmarshalStaxSource(Source staxSource)
                                        throws XmlMappingException

      Template method for handling `StaxSource`s.

      This implementation delegates to `unmarshalXmlStreamReader` or `unmarshalXmlEventReader`.

      Parameters:
        `staxSource` - the `StaxSource`
      Returns:
        the object graph
      Throws:
        `XmlMappingException` - if the given source cannot be mapped to an object

    - #### unmarshalSaxSource

          protected Object unmarshalSaxSource(SAXSource saxSource)
                                       throws XmlMappingException,
                                              IOException

      Template method for handling `SAXSource`s.

      This implementation delegates to `unmarshalSaxReader`.

      Parameters:
        `saxSource` - the `SAXSource`
      Returns:
        the object graph
      Throws:
        `XmlMappingException` - if the given source cannot be mapped to an object
        `IOException` - if an I/O Exception occurs
      See Also:
        `unmarshalSaxReader(org.xml.sax.XMLReader, org.xml.sax.InputSource)`

    - #### unmarshalStreamSource

          protected Object unmarshalStreamSource(StreamSource streamSource)
                                          throws XmlMappingException,
                                                 IOException

      Template method for handling `StreamSource`s.

      This implementation defers to `unmarshalInputStream` or `unmarshalReader`.

      Parameters:
        `streamSource` - the `StreamSource`
      Returns:
        the object graph
      Throws:
        `IOException` - if an I/O exception occurs
        `XmlMappingException` - if the given source cannot be mapped to an object

    - #### marshalDomNode

          protected abstract void marshalDomNode(Object graph,
                            Node node)
                                          throws XmlMappingException

      Abstract template method for marshalling the given object graph to a DOM `Node`.

      In practice, node is be a `Document` node, a `DocumentFragment` node, or a `Element` node. In other words, a node that accepts children.

      Parameters:
        `graph` - the root of the object graph to marshal
        `node` - the DOM node that will contain the result tree
      Throws:
        `XmlMappingException` - if the given object cannot be marshalled to the DOM node
      See Also:
        `Document`, `DocumentFragment`, `Element`

    - #### marshalXmlEventWriter

          protected abstract void marshalXmlEventWriter(Object graph,
                                   XMLEventWriter eventWriter)
                                                 throws XmlMappingException

      Abstract template method for marshalling the given object to a StAX `XMLEventWriter`.
      Parameters:
        `graph` - the root of the object graph to marshal
        `eventWriter` - the `XMLEventWriter` to write to
      Throws:
        `XmlMappingException` - if the given object cannot be marshalled to the DOM node

    - #### marshalXmlStreamWriter

          protected abstract void marshalXmlStreamWriter(Object graph,
                                    XMLStreamWriter streamWriter)
                                                  throws XmlMappingException

      Abstract template method for marshalling the given object to a StAX `XMLStreamWriter`.
      Parameters:
        `graph` - the root of the object graph to marshal
        `streamWriter` - the `XMLStreamWriter` to write to
      Throws:
        `XmlMappingException` - if the given object cannot be marshalled to the DOM node

    - #### marshalOutputStream

          protected abstract void marshalOutputStream(Object graph,
                                 OutputStream outputStream)
                                               throws XmlMappingException,
                                                      IOException

      Abstract template method for marshalling the given object graph to a `OutputStream`.
      Parameters:
        `graph` - the root of the object graph to marshal
        `outputStream` - the `OutputStream` to write to
      Throws:
        `XmlMappingException` - if the given object cannot be marshalled to the writer
        `IOException` - if an I/O exception occurs

    - #### marshalSaxHandlers

          protected abstract void marshalSaxHandlers(Object graph,
                                ContentHandler contentHandler,
                                LexicalHandler lexicalHandler)
                                              throws XmlMappingException

      Abstract template method for marshalling the given object graph to a SAX `ContentHandler`.
      Parameters:
        `graph` - the root of the object graph to marshal
        `contentHandler` - the SAX `ContentHandler`
        `lexicalHandler` - the SAX2 `LexicalHandler`. Can be `null`.
      Throws:
        `XmlMappingException` - if the given object cannot be marshalled to the handlers

    - #### marshalWriter

          protected abstract void marshalWriter(Object graph,
                           Writer writer)
                                         throws XmlMappingException,
                                                IOException

      Abstract template method for marshalling the given object graph to a `Writer`.
      Parameters:
        `graph` - the root of the object graph to marshal
        `writer` - the `Writer` to write to
      Throws:
        `XmlMappingException` - if the given object cannot be marshalled to the writer
        `IOException` - if an I/O exception occurs

    - #### unmarshalDomNode

          protected abstract Object unmarshalDomNode(Node node)
                                              throws XmlMappingException

      Abstract template method for unmarshalling from a given DOM `Node`.
      Parameters:
        `node` - the DOM node that contains the objects to be unmarshalled
      Returns:
        the object graph
      Throws:
        `XmlMappingException` - if the given DOM node cannot be mapped to an object

    - #### unmarshalXmlEventReader

          protected abstract Object unmarshalXmlEventReader(XMLEventReader eventReader)
                                                     throws XmlMappingException

      Abstract template method for unmarshalling from a given Stax `XMLEventReader`.
      Parameters:
        `eventReader` - the `XMLEventReader` to read from
      Returns:
        the object graph
      Throws:
        `XmlMappingException` - if the given event reader cannot be converted to an object

    - #### unmarshalXmlStreamReader

          protected abstract Object unmarshalXmlStreamReader(XMLStreamReader streamReader)
                                                      throws XmlMappingException

      Abstract template method for unmarshalling from a given Stax `XMLStreamReader`.
      Parameters:
        `streamReader` - the `XMLStreamReader` to read from
      Returns:
        the object graph
      Throws:
        `XmlMappingException` - if the given stream reader cannot be converted to an object

    - #### unmarshalInputStream

          protected abstract Object unmarshalInputStream(InputStream inputStream)
                                                  throws XmlMappingException,
                                                         IOException

      Abstract template method for unmarshalling from a given `InputStream`.
      Parameters:
        `inputStream` - the `InputStreamStream` to read from
      Returns:
        the object graph
      Throws:
        `XmlMappingException` - if the given stream cannot be converted to an object
        `IOException` - if an I/O exception occurs

    - #### unmarshalReader

          protected abstract Object unmarshalReader(Reader reader)
                                             throws XmlMappingException,
                                                    IOException

      Abstract template method for unmarshalling from a given `Reader`.
      Parameters:
        `reader` - the `Reader` to read from
      Returns:
        the object graph
      Throws:
        `XmlMappingException` - if the given reader cannot be converted to an object
        `IOException` - if an I/O exception occurs

    - #### unmarshalSaxReader

          protected abstract Object unmarshalSaxReader(XMLReader xmlReader,
                                  InputSource inputSource)
                                                throws XmlMappingException,
                                                       IOException

      Abstract template method for unmarshalling using a given SAX `XMLReader` and `InputSource`.
      Parameters:
        `xmlReader` - the SAX `XMLReader` to parse with
        `inputSource` - the input source to parse from
      Returns:
        the object graph
      Throws:
        `XmlMappingException` - if the given reader and input source cannot be converted to an object
        `IOException` - if an I/O exception occurs