org.springframework.oxm.castor
Class CastorMarshaller

java.lang.Object
  org.springframework.oxm.AbstractMarshaller
      org.springframework.oxm.castor.CastorMarshaller

All Implemented Interfaces:

org.springframework.beans.factory.InitializingBean, Marshaller, Unmarshaller

public class CastorMarshaller
extends AbstractMarshaller
implements org.springframework.beans.factory.InitializingBean

Implementation of the Marshaller interface for Castor. By default, Castor does not require any further configuration, though setting a target class or providing a mapping file can be used to have more control over the behavior of Castor.

If a target class is specified using setTargetClass, the CastorMarshaller can only be used to unmarshall XML that represents that specific class. If you want to unmarshall multiple classes, you have to provide a mapping file using setMappingLocations.

Due to Castor's API, it is required to set the encoding used for writing to output streams. It defaults to UTF-8.

Since:

1.0.0

Author:

Arjen Poutsma

See Also:

setEncoding(String), setTargetClass(Class), setMappingLocation(org.springframework.core.io.Resource), setMappingLocations(org.springframework.core.io.Resource[])

Field Summary

static java.lang.String

DEFAULT_ENCODING The default encoding used for stream access.

Fields inherited from class org.springframework.oxm.AbstractMarshaller

logger

Constructor Summary

CastorMarshaller()

Method Summary

void	afterPropertiesSet()
XmlMappingException	convertCastorException(org.exolab.castor.xml.XMLException ex, boolean marshalling) Converts the given CastorException to an appropriate exception from the org.springframework.oxm hierarchy.
protected org.exolab.castor.xml.XMLContext	createXMLContext(org.springframework.core.io.Resource[] mappingLocations, java.lang.Class targetClass) Creates the Castor XMLContext.
protected void	customizeMarshaller(org.exolab.castor.xml.Marshaller marshaller) Template method that allows for customizing of the given Castor Marshaller.
protected void	customizeUnmarshaller(org.exolab.castor.xml.Unmarshaller unmarshaller) Template method that allows for customizing of the given Castor Unmarshaller.
boolean	getIgnoreExtraAttributes() Returns whether the Castor Unmarshaller should ignore attributes that do not match a specific field.
boolean	getIgnoreExtraElements() Returns whether the Castor Unmarshaller should ignore elements that do not match a specific field.
java.util.Properties	getNamespaceMappings() Returns the namespace mappings.
boolean	getWhitespacePreserve() Returns whether the Castor Unmarshaller should preserve "ignorable" whitespace.
boolean	isSuppressNamespaces() Returns whether this marshaller should output namespaces.
boolean	isSuppressXsiType() Sets whether this marshaller should output the xsi:type attribute.
boolean	isValidating() Returns whether this marshaller should validate in- and outgoing documents.
protected 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	marshalOutputStream(java.lang.Object graph, java.io.OutputStream outputStream) Abstract template method for marshalling the given object graph to a OutputStream.
protected 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	marshalWriter(java.lang.Object graph, java.io.Writer writer) Abstract template method for marshalling the given object graph to a Writer.
protected void	marshalXmlEventWriter(java.lang.Object graph, javax.xml.stream.XMLEventWriter eventWriter) Abstract template method for marshalling the given object to a StAX XMLEventWriter.
protected void	marshalXmlStreamWriter(java.lang.Object graph, javax.xml.stream.XMLStreamWriter streamWriter) Abstract template method for marshalling the given object to a StAX XMLStreamWriter.
void	setEncoding(java.lang.String encoding) Sets the encoding to be used for stream access.
void	setIgnoreExtraAttributes(boolean ignoreExtraAttributes) Sets whether the Castor Unmarshaller should ignore attributes that do not match a specific field.
void	setIgnoreExtraElements(boolean ignoreExtraElements) Sets whether the Castor Unmarshaller should ignore elements that do not match a specific field.
void	setMappingLocation(org.springframework.core.io.Resource mappingLocation) Sets the locations of the Castor XML Mapping files.
void	setMappingLocations(org.springframework.core.io.Resource[] mappingLocations) Sets the locations of the Castor XML Mapping files.
void	setNamespaceMappings(java.util.Properties namespaceMappings) Sets the namespace mappings.
void	setSuppressNamespaces(boolean suppressNamespaces) Sets whether this marshaller should output namespaces.
void	setSuppressXsiType(boolean suppressXsiType) Sets whether this marshaller should output the xsi:type attribute.
void	setTargetClass(java.lang.Class targetClass) Sets the Castor target class.
void	setValidating(boolean validating) Sets whether this marshaller should validate in- and outgoing documents.
void	setWhitespacePreserve(boolean whitespacePreserve) Sets whether the Castor Unmarshaller should preserve "ignorable" whitespace.
boolean	supports(java.lang.Class clazz) Returns true for all classes, i.e.
protected java.lang.Object	unmarshalDomNode(org.w3c.dom.Node node) Abstract template method for unmarshalling from a given DOM Node.
protected java.lang.Object	unmarshalInputStream(java.io.InputStream inputStream) Abstract template method for unmarshalling from a given InputStream.
protected java.lang.Object	unmarshalReader(java.io.Reader reader) Abstract template method for unmarshalling from a given Reader.
protected 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	unmarshalXmlEventReader(javax.xml.stream.XMLEventReader eventReader) Abstract template method for unmarshalling from a given Stax XMLEventReader.
protected java.lang.Object	unmarshalXmlStreamReader(javax.xml.stream.XMLStreamReader streamReader) Abstract template method for unmarshalling from a given Stax XMLStreamReader.

Methods inherited from class org.springframework.oxm.AbstractMarshaller

createDocumentBuilder, createDocumentBuilderFactory, createXmlReader, marshal, marshalDomResult, marshalSaxResult, marshalStaxResult, marshalStreamResult, unmarshal, unmarshalDomSource, unmarshalSaxSource, unmarshalStaxSource, unmarshalStreamSource

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ENCODING

public static final java.lang.String DEFAULT_ENCODING

The default encoding used for stream access.

See Also:

Constant Field Values

Constructor Detail

CastorMarshaller

public CastorMarshaller()

Method Detail

getIgnoreExtraAttributes

public boolean getIgnoreExtraAttributes()

Returns whether the Castor Unmarshaller should ignore attributes that do not match a specific field.

setIgnoreExtraAttributes

public void setIgnoreExtraAttributes(boolean ignoreExtraAttributes)

Sets whether the Castor Unmarshaller should ignore attributes that do not match a specific field. Default is true: extra attributes are ignored.

See Also:

Unmarshaller.setIgnoreExtraAttributes(boolean)

getIgnoreExtraElements

public boolean getIgnoreExtraElements()

Returns whether the Castor Unmarshaller should ignore elements that do not match a specific field.

setIgnoreExtraElements

public void setIgnoreExtraElements(boolean ignoreExtraElements)

Sets whether the Castor Unmarshaller should ignore elements that do not match a specific field. Default is false, extra attributes are flagged as an error.

See Also:

Unmarshaller.setIgnoreExtraElements(boolean)

getWhitespacePreserve

public boolean getWhitespacePreserve()

Returns whether the Castor Unmarshaller should preserve "ignorable" whitespace.

setWhitespacePreserve

public void setWhitespacePreserve(boolean whitespacePreserve)

Sets whether the Castor Unmarshaller should preserve "ignorable" whitespace. Default is false.

See Also:

Unmarshaller.setWhitespacePreserve(boolean)

isValidating

public boolean isValidating()

Returns whether this marshaller should validate in- and outgoing documents.

setValidating

public void setValidating(boolean validating)

Sets whether this marshaller should validate in- and outgoing documents. Default is false.

See Also:

Marshaller.setValidation(boolean)

getNamespaceMappings

public java.util.Properties getNamespaceMappings()

Returns the namespace mappings. Property names are interpreted as namespace prefixes; values are namespace URIs.

setNamespaceMappings

public void setNamespaceMappings(java.util.Properties namespaceMappings)

Sets the namespace mappings. Property names are interpreted as namespace prefixes; values are namespace URIs.

See Also:

Marshaller.setNamespaceMapping(String, String)

setEncoding

public void setEncoding(java.lang.String encoding)

Sets the encoding to be used for stream access. If this property is not set, the default encoding is used.

See Also:

DEFAULT_ENCODING

setMappingLocation

public void setMappingLocation(org.springframework.core.io.Resource mappingLocation)

Sets the locations of the Castor XML Mapping files.

setMappingLocations

public void setMappingLocations(org.springframework.core.io.Resource[] mappingLocations)

Sets the locations of the Castor XML Mapping files.

isSuppressNamespaces

public boolean isSuppressNamespaces()

Returns whether this marshaller should output namespaces.

setSuppressNamespaces

public void setSuppressNamespaces(boolean suppressNamespaces)

Sets whether this marshaller should output namespaces. The default is false, i.e. namespaces are written.

See Also:

Marshaller.setSuppressNamespaces(boolean)

isSuppressXsiType

public boolean isSuppressXsiType()

Sets whether this marshaller should output the xsi:type attribute.

setSuppressXsiType

public void setSuppressXsiType(boolean suppressXsiType)

Sets whether this marshaller should output the xsi:type attribute. The default is false, i.e. the xsi:type is written.

See Also:

Marshaller.setSuppressXSIType(boolean)

setTargetClass

public void setTargetClass(java.lang.Class targetClass)

Sets the Castor target class. If this property is set, this CastorMarshaller is tied to this one specific class. Use a mapping file for unmarshalling multiple classes.

afterPropertiesSet

public final void afterPropertiesSet()
                              throws java.io.IOException

Specified by:

afterPropertiesSet in interface org.springframework.beans.factory.InitializingBean

Throws:

java.io.IOException

supports

public boolean supports(java.lang.Class clazz)

Returns true for all classes, i.e. Castor supports arbitrary classes.

Specified by:

supports in interface Marshaller

Specified by:

supports in interface Unmarshaller

Parameters:

clazz - the class that this marshaller is being asked if it can marshal

Returns:

true if this marshaller can indeed marshal instances of the supplied class; false otherwise

createXMLContext

protected org.exolab.castor.xml.XMLContext createXMLContext(org.springframework.core.io.Resource[] mappingLocations,
                                                            java.lang.Class targetClass)
                                                     throws org.exolab.castor.mapping.MappingException,
                                                            java.io.IOException,
                                                            org.exolab.castor.xml.ResolverException

Creates the Castor XMLContext. Subclasses can override this to create a custom context.

The default implementation loads mapping files if defined, and the target class if not defined.

Returns:

the created resolver

Throws:

org.exolab.castor.mapping.MappingException - when the mapping file cannot be loaded

java.io.IOException - in case of I/O errors

org.exolab.castor.xml.ResolverException

See Also:

XMLContext.addMapping(org.exolab.castor.mapping.Mapping), XMLContext.addClass(Class)

marshalDomNode

protected final void marshalDomNode(java.lang.Object graph,
                                    org.w3c.dom.Node node)
                             throws XmlMappingException

Description copied from class: AbstractMarshaller

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.

Specified by:

marshalDomNode in class AbstractMarshaller

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

marshalSaxHandlers

protected final void marshalSaxHandlers(java.lang.Object graph,
                                        org.xml.sax.ContentHandler contentHandler,
                                        org.xml.sax.ext.LexicalHandler lexicalHandler)
                                 throws XmlMappingException

Description copied from class: AbstractMarshaller

Abstract template method for marshalling the given object graph to a SAX ContentHandler.

Specified by:

marshalSaxHandlers in class AbstractMarshaller

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 final void marshalOutputStream(java.lang.Object graph,
                                         java.io.OutputStream outputStream)
                                  throws XmlMappingException,
                                         java.io.IOException

Description copied from class: AbstractMarshaller

Abstract template method for marshalling the given object graph to a OutputStream.

Specified by:

marshalOutputStream in class AbstractMarshaller

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

marshalWriter

protected final void marshalWriter(java.lang.Object graph,
                                   java.io.Writer writer)
                            throws XmlMappingException,
                                   java.io.IOException

Description copied from class: AbstractMarshaller

Abstract template method for marshalling the given object graph to a Writer.

Specified by:

marshalWriter in class AbstractMarshaller

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

marshalXmlEventWriter

protected final void marshalXmlEventWriter(java.lang.Object graph,
                                           javax.xml.stream.XMLEventWriter eventWriter)
                                    throws XmlMappingException

Description copied from class: AbstractMarshaller

Abstract template method for marshalling the given object to a StAX XMLEventWriter.

Specified by:

marshalXmlEventWriter in class AbstractMarshaller

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 final void marshalXmlStreamWriter(java.lang.Object graph,
                                            javax.xml.stream.XMLStreamWriter streamWriter)
                                     throws XmlMappingException

Description copied from class: AbstractMarshaller

Abstract template method for marshalling the given object to a StAX XMLStreamWriter.

Specified by:

marshalXmlStreamWriter in class AbstractMarshaller

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

customizeMarshaller

protected void customizeMarshaller(org.exolab.castor.xml.Marshaller marshaller)

Template method that allows for customizing of the given Castor Marshaller.

Default implementation invokes Marshaller.setValidation(boolean) with the property set on this marshaller, and calls Marshaller.setNamespaceMapping(String, String) with the namespace mappings.

unmarshalDomNode

protected final java.lang.Object unmarshalDomNode(org.w3c.dom.Node node)
                                           throws XmlMappingException

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling from a given DOM Node.

Specified by:

unmarshalDomNode in class AbstractMarshaller

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

unmarshalInputStream

protected final java.lang.Object unmarshalInputStream(java.io.InputStream inputStream)
                                               throws XmlMappingException,
                                                      java.io.IOException

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling from a given InputStream.

Specified by:

unmarshalInputStream in class AbstractMarshaller

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 final java.lang.Object unmarshalReader(java.io.Reader reader)
                                          throws XmlMappingException,
                                                 java.io.IOException

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling from a given Reader.

Specified by:

unmarshalReader in class AbstractMarshaller

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

unmarshalXmlEventReader

protected final java.lang.Object unmarshalXmlEventReader(javax.xml.stream.XMLEventReader eventReader)

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling from a given Stax XMLEventReader.

Specified by:

unmarshalXmlEventReader in class AbstractMarshaller

Parameters:

eventReader - The XMLEventReader to read from

Returns:

the object graph

unmarshalSaxReader

protected final java.lang.Object unmarshalSaxReader(org.xml.sax.XMLReader xmlReader,
                                                    org.xml.sax.InputSource inputSource)
                                             throws XmlMappingException,
                                                    java.io.IOException

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling using a given SAX XMLReader and InputSource.

Specified by:

unmarshalSaxReader in class AbstractMarshaller

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

unmarshalXmlStreamReader

protected final java.lang.Object unmarshalXmlStreamReader(javax.xml.stream.XMLStreamReader streamReader)

Description copied from class: AbstractMarshaller

Abstract template method for unmarshalling from a given Stax XMLStreamReader.

Specified by:

unmarshalXmlStreamReader in class AbstractMarshaller

Parameters:

streamReader - The XMLStreamReader to read from

Returns:

the object graph

customizeUnmarshaller

protected void customizeUnmarshaller(org.exolab.castor.xml.Unmarshaller unmarshaller)

Template method that allows for customizing of the given Castor Unmarshaller.

Default implementation invokes Unmarshaller.setValidation(boolean), Unmarshaller.setWhitespacePreserve(boolean), Unmarshaller.setIgnoreExtraAttributes(boolean), and Unmarshaller.setIgnoreExtraElements(boolean) with the properties set on this marshaller.

convertCastorException

public XmlMappingException convertCastorException(org.exolab.castor.xml.XMLException ex,
                                                  boolean marshalling)

Converts the given CastorException to an appropriate exception from the org.springframework.oxm hierarchy.

The default implementation delegates to CastorUtils. Can be overridden in subclasses.

A boolean flag is used to indicate whether this exception occurs during marshalling or unmarshalling, since Castor itself does not make this distinction in its exception hierarchy.

Parameters:

ex - Castor XMLException that occured

marshalling - indicates whether the exception occurs during marshalling (true), or unmarshalling (false)

Returns:

the corresponding XmlMappingException

See Also:

CastorUtils.convertXmlException(org.exolab.castor.xml.XMLException, boolean)