org.springframework.oxm.support

## Class AbstractMarshaller

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

All Implemented Interfaces:
  Marshaller, Unmarshaller

Direct Known Subclasses:
  JibxMarshaller, 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 delegates further handling to overridable template methods.

Since:
  3.0
Author:
  Arjen Poutsma, Juergen Hoeller

### Field Summary

Fields
`protected Log` `logger` Logger available to subclasses.

### Constructor Summary

Constructors
Constructor and Description
`AbstractMarshaller()`

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`protected Document` `buildDocument()` Build a new `Document` from this marshaller's `DocumentBuilderFactory`, as a placeholder for a DOM node.
`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 an `XMLReader` that this marshaller will when passed an empty `SAXSource`.
`protected String` `getDefaultEncoding()` Determine the default encoding to use for marshalling or unmarshalling from a byte stream, or `null` if none.
`boolean` `isProcessExternalEntities()` Return whether XML external entities are allowed.
`boolean` `isSupportDtd()` Return whether DTD parsing is supported.
`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`.
`void` `setProcessExternalEntities(boolean processExternalEntities)` Indicate whether external XML entities are processed when unmarshalling.
`void` `setSupportDtd(boolean supportDtd)` Indicate whether DTD parsing should be supported.
`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

#### setSupportDtd

    public void setSupportDtd(boolean supportDtd)

Indicate whether DTD parsing should be supported.

Default is `false` meaning that DTD is disabled.

#### isSupportDtd

    public boolean isSupportDtd()

Return whether DTD parsing is supported.

#### setProcessExternalEntities

    public void setProcessExternalEntities(boolean processExternalEntities)

Indicate whether external XML entities are processed when unmarshalling.

Default is `false`, meaning that external entities are not resolved. Note that processing of external entities will only be enabled/disabled when the `Source` passed to `unmarshal(Source)` is a `SAXSource` or `StreamSource`. It has no effect for `DOMSource` or `StAXSource` instances.

Note: setting this option to `true` also automatically sets `setSupportDtd(boolean)` to `true`.

#### isProcessExternalEntities

    public boolean isProcessExternalEntities()

Return whether XML external entities are allowed.

See Also:
  `createXmlReader()`

#### buildDocument

    protected Document buildDocument()

Build a new `Document` from this marshaller's `DocumentBuilderFactory`, as a placeholder for a DOM node.

See Also:
  `createDocumentBuilderFactory()`, `createDocumentBuilder(DocumentBuilderFactory)`

#### 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

#### 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

#### createXmlReader

    protected XMLReader createXmlReader()
                                 throws SAXException

Create an `XMLReader` that this marshaller will when passed an empty `SAXSource`.

Returns:
  the XMLReader
Throws:
  `SAXException` - if thrown by JAXP methods

#### getDefaultEncoding

    @Nullable
    protected String getDefaultEncoding()

Determine the default encoding to use for marshalling or unmarshalling from a byte stream, or `null` if none.

The default implementation returns `null`.

#### 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)`

#### 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 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`

#### 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)`

#### 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 delegates 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

#### marshalSaxHandlers

    protected abstract void marshalSaxHandlers(Object graph,
                                               ContentHandler contentHandler,
                                               @Nullable
                                               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

#### 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

#### 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

#### 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

#### 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