Spring Framework

org.springframework.oxm.support
Class AbstractMarshaller

java.lang.Object
  extended by org.springframework.oxm.support.AbstractMarshaller
All Implemented Interfaces:
Marshaller, Unmarshaller
Direct Known Subclasses:
CastorMarshaller, JibxMarshaller, XmlBeansMarshaller, XStreamMarshaller

public abstract class AbstractMarshaller
extends java.lang.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
protected  org.apache.commons.logging.Log logger
          Logger available to subclasses.
 
Constructor Summary
AbstractMarshaller()
           
 
Method Summary
protected  javax.xml.parsers.DocumentBuilder createDocumentBuilder(javax.xml.parsers.DocumentBuilderFactory factory)
          Create a DocumentBuilder that this marshaller will use for creating DOM documents when passed an empty DOMSource.
protected  javax.xml.parsers.DocumentBuilderFactory createDocumentBuilderFactory()
          Create a DocumentBuilder that this marshaller will use for creating DOM documents when passed an empty DOMSource.
protected  org.xml.sax.XMLReader createXmlReader()
          Create a XMLReader that this marshaller will when passed an empty SAXSource.
 void marshal(java.lang.Object graph, javax.xml.transform.Result result)
          Marshals the object graph with the given root into the provided javax.xml.transform.Result.
protected abstract  void marshalDomNode(java.lang.Object graph, org.w3c.dom.Node node)
          Abstract template method for marshalling the given object graph to a DOM Node.
protected  void marshalDomResult(java.lang.Object graph, javax.xml.transform.dom.DOMResult domResult)
          Template method for handling DOMResults.
protected abstract  void marshalOutputStream(java.lang.Object graph, java.io.OutputStream outputStream)
          Abstract template method for marshalling the given object graph to a OutputStream.
protected abstract  void marshalSaxHandlers(java.lang.Object graph, org.xml.sax.ContentHandler contentHandler, org.xml.sax.ext.LexicalHandler lexicalHandler)
          Abstract template method for marshalling the given object graph to a SAX ContentHandler.
protected  void marshalSaxResult(java.lang.Object graph, javax.xml.transform.sax.SAXResult saxResult)
          Template method for handling SAXResults.
protected  void marshalStaxResult(java.lang.Object graph, javax.xml.transform.Result staxResult)
          Template method for handling StaxResults.
protected  void marshalStreamResult(java.lang.Object graph, javax.xml.transform.stream.StreamResult streamResult)
          Template method for handling StreamResults.
protected abstract  void marshalWriter(java.lang.Object graph, java.io.Writer writer)
          Abstract template method for marshalling the given object graph to a Writer.
protected abstract  void marshalXmlEventWriter(java.lang.Object graph, javax.xml.stream.XMLEventWriter eventWriter)
          Abstract template method for marshalling the given object to a StAX XMLEventWriter.
protected abstract  void marshalXmlStreamWriter(java.lang.Object graph, javax.xml.stream.XMLStreamWriter streamWriter)
          Abstract template method for marshalling the given object to a StAX XMLStreamWriter.
 java.lang.Object unmarshal(javax.xml.transform.Source source)
          Unmarshals the given provided javax.xml.transform.Source into an object graph.
protected abstract  java.lang.Object unmarshalDomNode(org.w3c.dom.Node node)
          Abstract template method for unmarshalling from a given DOM Node.
protected  java.lang.Object unmarshalDomSource(javax.xml.transform.dom.DOMSource domSource)
          Template method for handling DOMSources.
protected abstract  java.lang.Object unmarshalInputStream(java.io.InputStream inputStream)
          Abstract template method for unmarshalling from a given InputStream.
protected abstract  java.lang.Object unmarshalReader(java.io.Reader reader)
          Abstract template method for unmarshalling from a given Reader.
protected abstract  java.lang.Object unmarshalSaxReader(org.xml.sax.XMLReader xmlReader, org.xml.sax.InputSource inputSource)
          Abstract template method for unmarshalling using a given SAX XMLReader and InputSource.
protected  java.lang.Object unmarshalSaxSource(javax.xml.transform.sax.SAXSource saxSource)
          Template method for handling SAXSources.
protected  java.lang.Object unmarshalStaxSource(javax.xml.transform.Source staxSource)
          Template method for handling StaxSources.
protected  java.lang.Object unmarshalStreamSource(javax.xml.transform.stream.StreamSource streamSource)
          Template method for handling StreamSources.
protected abstract  java.lang.Object unmarshalXmlEventReader(javax.xml.stream.XMLEventReader eventReader)
          Abstract template method for unmarshalling from a given Stax XMLEventReader.
protected abstract  java.lang.Object unmarshalXmlStreamReader(javax.xml.stream.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 org.apache.commons.logging.Log logger
Logger available to subclasses.

Constructor Detail

AbstractMarshaller

public AbstractMarshaller()
Method Detail

marshal

public final void marshal(java.lang.Object graph,
                          javax.xml.transform.Result result)
                   throws java.io.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:
java.io.IOException - if an I/O exception occurs
XmlMappingException - if the given object cannot be marshalled to the result
java.lang.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 java.lang.Object unmarshal(javax.xml.transform.Source source)
                                 throws java.io.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:
java.io.IOException - if an I/O Exception occurs
XmlMappingException - if the given source cannot be mapped to an object
java.lang.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 javax.xml.parsers.DocumentBuilder createDocumentBuilder(javax.xml.parsers.DocumentBuilderFactory factory)
                                                           throws javax.xml.parsers.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:
javax.xml.parsers.ParserConfigurationException - if thrown by JAXP methods

createDocumentBuilderFactory

protected javax.xml.parsers.DocumentBuilderFactory createDocumentBuilderFactory()
                                                                         throws javax.xml.parsers.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:
javax.xml.parsers.ParserConfigurationException - if thrown by JAXP methods

createXmlReader

protected org.xml.sax.XMLReader createXmlReader()
                                         throws org.xml.sax.SAXException
Create a XMLReader that this marshaller will when passed an empty SAXSource.

Returns:
the XMLReader
Throws:
org.xml.sax.SAXException - if thrown by JAXP methods

marshalDomResult

protected void marshalDomResult(java.lang.Object graph,
                                javax.xml.transform.dom.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
java.lang.IllegalArgumentException - if the domResult is empty
See Also:
marshalDomNode(Object, org.w3c.dom.Node)

marshalStaxResult

protected void marshalStaxResult(java.lang.Object graph,
                                 javax.xml.transform.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 Spring StaxSource or JAXP 1.4 StAXSource
Throws:
XmlMappingException - if the given object cannot be marshalled to the result
java.lang.IllegalArgumentException - if the domResult is empty
See Also:
marshalDomNode(Object,org.w3c.dom.Node)

marshalSaxResult

protected void marshalSaxResult(java.lang.Object graph,
                                javax.xml.transform.sax.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(java.lang.Object graph,
                                   javax.xml.transform.stream.StreamResult streamResult)
                            throws XmlMappingException,
                                   java.io.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:
java.io.IOException - if an I/O Exception occurs
XmlMappingException - if the given object cannot be marshalled to the result
java.lang.IllegalArgumentException - if streamResult does neither contain an OutputStream nor a Writer

unmarshalDomSource

protected java.lang.Object unmarshalDomSource(javax.xml.transform.dom.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
java.lang.IllegalArgumentException - if the domSource is empty
See Also:
unmarshalDomNode(org.w3c.dom.Node)

unmarshalStaxSource

protected java.lang.Object unmarshalStaxSource(javax.xml.transform.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 java.lang.Object unmarshalSaxSource(javax.xml.transform.sax.SAXSource saxSource)
                                       throws XmlMappingException,
                                              java.io.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
java.io.IOException - if an I/O Exception occurs
See Also:
unmarshalSaxReader(org.xml.sax.XMLReader, org.xml.sax.InputSource)

unmarshalStreamSource

protected java.lang.Object unmarshalStreamSource(javax.xml.transform.stream.StreamSource streamSource)
                                          throws XmlMappingException,
                                                 java.io.IOException
Template method for handling StreamSources.

This implementation defers to unmarshalInputStream or unmarshalReader.

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

marshalDomNode

protected abstract void marshalDomNode(java.lang.Object graph,
                                       org.w3c.dom.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(java.lang.Object graph,
                                              javax.xml.stream.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(java.lang.Object graph,
                                               javax.xml.stream.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(java.lang.Object graph,
                                            java.io.OutputStream outputStream)
                                     throws XmlMappingException,
                                            java.io.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
java.io.IOException - if an I/O exception occurs

marshalSaxHandlers

protected abstract void marshalSaxHandlers(java.lang.Object graph,
                                           org.xml.sax.ContentHandler contentHandler,
                                           org.xml.sax.ext.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(java.lang.Object graph,
                                      java.io.Writer writer)
                               throws XmlMappingException,
                                      java.io.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
java.io.IOException - if an I/O exception occurs

unmarshalDomNode

protected abstract java.lang.Object unmarshalDomNode(org.w3c.dom.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 java.lang.Object unmarshalXmlEventReader(javax.xml.stream.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 java.lang.Object unmarshalXmlStreamReader(javax.xml.stream.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 java.lang.Object unmarshalInputStream(java.io.InputStream inputStream)
                                                  throws XmlMappingException,
                                                         java.io.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
java.io.IOException - if an I/O exception occurs

unmarshalReader

protected abstract java.lang.Object unmarshalReader(java.io.Reader reader)
                                             throws XmlMappingException,
                                                    java.io.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
java.io.IOException - if an I/O exception occurs

unmarshalSaxReader

protected abstract java.lang.Object unmarshalSaxReader(org.xml.sax.XMLReader xmlReader,
                                                       org.xml.sax.InputSource inputSource)
                                                throws XmlMappingException,
                                                       java.io.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
java.io.IOException - if an I/O exception occurs

Spring Framework