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

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 an XMLReader that this marshaller will when passed an empty SAXSource.
protected abstract String	getDefaultEncoding()
boolean	isProcessExternalEntities()
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 DOMResults.
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 SAXResults.
protected void	marshalStaxResult(Object graph, Result staxResult) Template method for handling StaxResults.
protected void	marshalStreamResult(Object graph, StreamResult streamResult) Template method for handling StreamResults.
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) Indicates whether external XML entities are processed when unmarshalling.
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 DOMSources.
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 SAXSources.
protected Object	unmarshalStaxSource(Source staxSource) Template method for handling StaxSources.
protected Object	unmarshalStreamSource(StreamSource streamSource) Template method for handling StreamSources.
protected Object	unmarshalStreamSourceNoExternalEntitities(StreamSource streamSource) Template method for handling StreamSources with protection against the XML External Entity (XXE) processing vulnerability taking into account the value of the setProcessExternalEntities(boolean) property.
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

setProcessExternalEntities

public void setProcessExternalEntities(boolean processExternalEntities)

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

isProcessExternalEntities

public boolean isProcessExternalEntities()

Returns:

the configured value for whether XML external entities are allowed.

getDefaultEncoding

protected abstract String getDefaultEncoding()

Returns:

the default encoding to use for marshalling or unmarshalling from a byte stream, or 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)

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 an 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 DOMResults.

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

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

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

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

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

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

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)

unmarshalStreamSourceNoExternalEntitities

protected Object unmarshalStreamSourceNoExternalEntitities(StreamSource streamSource)
                                                    throws XmlMappingException,
                                                           IOException

Template method for handling StreamSources with protection against the XML External Entity (XXE) processing vulnerability taking into account the value of the setProcessExternalEntities(boolean) property.

The default implementation wraps the StreamSource as a SAXSource and delegates to unmarshalSaxSource(javax.xml.transform.sax.SAXSource).

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

See Also:

XML_External_Entity_(XXE)_Processing

unmarshalStreamSource

protected Object unmarshalStreamSource(StreamSource streamSource)
                                throws XmlMappingException,
                                       IOException

Template method for handling StreamSources.

This implementation defers to unmarshalInputStream or unmarshalReader.

As of 3.2.8 and 4.0.2 this method is no longer invoked from unmarshal(javax.xml.transform.Source). The method invoked instead is unmarshalStreamSourceNoExternalEntitities(javax.xml.transform.stream.StreamSource).

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