org.springframework.oxm.castor
Class CastorMarshaller

java.lang.Object
  extended by org.springframework.oxm.support.AbstractMarshaller
      extended by org.springframework.oxm.castor.CastorMarshaller
All Implemented Interfaces:
InitializingBean, Marshaller, Unmarshaller

public class CastorMarshaller
extends AbstractMarshaller
implements InitializingBean

Implementation of the Marshaller interface for Castor. By default, Castor does not require any further configuration, though setting target classes, target packages 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 limitations of Castor's API, it is required to set the encoding used for writing to output streams. It defaults to UTF-8.

Since:
3.0
Author:
Arjen Poutsma
See Also:
setEncoding(String), setTargetClass(Class), setTargetPackages(String[]), setMappingLocation(Resource), setMappingLocations(Resource[])

Field Summary
static String DEFAULT_ENCODING
          The default encoding used for stream access: UTF-8.
 
Fields inherited from class org.springframework.oxm.support.AbstractMarshaller
logger
 
Constructor Summary
CastorMarshaller()
           
 
Method Summary
 void afterPropertiesSet()
          Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
protected  XmlMappingException convertCastorException(org.exolab.castor.xml.XMLException ex, boolean marshalling)
          Convert the given XMLException to an appropriate exception from the org.springframework.oxm hierarchy.
protected  org.exolab.castor.xml.XMLContext createXMLContext(Resource[] mappingLocations, Class[] targetClasses, String[] targetPackages)
          Create 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 isSuppressNamespaces()
          Returns whether this marshaller should output namespaces.
 boolean isSuppressXsiType()
          Sets whether this marshaller should output the xsi:type attribute.
protected  void marshalDomNode(Object graph, Node node)
          Abstract template method for marshalling the given object graph to a DOM Node.
protected  void marshalOutputStream(Object graph, OutputStream outputStream)
          Abstract template method for marshalling the given object graph to a OutputStream.
protected  void marshalSaxHandlers(Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler)
          Abstract template method for marshalling the given object graph to a SAX ContentHandler.
protected  void marshalWriter(Object graph, Writer writer)
          Abstract template method for marshalling the given object graph to a Writer.
protected  void marshalXmlEventWriter(Object graph, XMLEventWriter eventWriter)
          Abstract template method for marshalling the given object to a StAX XMLEventWriter.
protected  void marshalXmlStreamWriter(Object graph, XMLStreamWriter streamWriter)
          Abstract template method for marshalling the given object to a StAX XMLStreamWriter.
 void setEncoding(String encoding)
          Set the encoding to be used for stream access.
 void setIgnoreExtraAttributes(boolean ignoreExtraAttributes)
          Set whether the Castor Unmarshaller should ignore attributes that do not match a specific field.
 void setIgnoreExtraElements(boolean ignoreExtraElements)
          Set whether the Castor Unmarshaller should ignore elements that do not match a specific field.
 void setMappingLocation(Resource mappingLocation)
          Set the locations of the Castor XML Mapping files.
 void setMappingLocations(Resource[] mappingLocations)
          Set the locations of the Castor XML Mapping files.
 void setNamespaceMappings(Map<String,String> namespaceMappings)
          Set 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(Class targetClass)
          Set the Castor target class.
 void setTargetClasses(Class[] targetClasses)
          Set the Castor target classes.
 void setTargetPackages(String[] targetPackages)
          Set the package names of packages with the Castor descriptor classes.
 void setValidating(boolean validating)
          Set whether this marshaller should validate in- and outgoing documents.
 void setWhitespacePreserve(boolean whitespacePreserve)
          Set whether the Castor Unmarshaller should preserve "ignorable" whitespace.
 boolean supports(Class<?> clazz)
          Returns true for all classes, i.e.
protected  Object unmarshalDomNode(Node node)
          Abstract template method for unmarshalling from a given DOM Node.
protected  Object unmarshalInputStream(InputStream inputStream)
          Abstract template method for unmarshalling from a given InputStream.
protected  Object unmarshalReader(Reader reader)
          Abstract template method for unmarshalling from a given Reader.
protected  Object unmarshalSaxReader(XMLReader xmlReader, InputSource inputSource)
          Abstract template method for unmarshalling using a given SAX XMLReader and InputSource.
protected  Object unmarshalXmlEventReader(XMLEventReader eventReader)
          Abstract template method for unmarshalling from a given Stax XMLEventReader.
protected  Object unmarshalXmlStreamReader(XMLStreamReader streamReader)
          Abstract template method for unmarshalling from a given Stax XMLStreamReader.
 
Methods inherited from class org.springframework.oxm.support.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 String DEFAULT_ENCODING
The default encoding used for stream access: UTF-8.

See Also:
Constant Field Values
Constructor Detail

CastorMarshaller

public CastorMarshaller()
Method Detail

setEncoding

public void setEncoding(String encoding)
Set the encoding to be used for stream access.

See Also:
DEFAULT_ENCODING

setMappingLocation

public void setMappingLocation(Resource mappingLocation)
Set the locations of the Castor XML Mapping files.


setMappingLocations

public void setMappingLocations(Resource[] mappingLocations)
Set the locations of the Castor XML Mapping files.


setTargetClass

public void setTargetClass(Class targetClass)
Set the Castor target class. Alternative means of configuring CastorMarshaller for unmarshalling multiple classes include use of mapping files, and specifying packages with Castor descriptor classes.


setTargetClasses

public void setTargetClasses(Class[] targetClasses)
Set the Castor target classes. Alternative means of configuring CastorMarshaller for unmarshalling multiple classes include use of mapping files, and specifying packages with Castor descriptor classes.


setTargetPackages

public void setTargetPackages(String[] targetPackages)
Set the package names of packages with the Castor descriptor classes.


setValidating

public void setValidating(boolean validating)
Set whether this marshaller should validate in- and outgoing documents.

Default is false.

See Also:
Marshaller.setValidation(boolean)

setWhitespacePreserve

public void setWhitespacePreserve(boolean whitespacePreserve)
Set whether the Castor Unmarshaller should preserve "ignorable" whitespace.

Default is false.

See Also:
Unmarshaller.setWhitespacePreserve(boolean)

setIgnoreExtraAttributes

public void setIgnoreExtraAttributes(boolean ignoreExtraAttributes)
Set 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)

setIgnoreExtraElements

public void setIgnoreExtraElements(boolean ignoreExtraElements)
Set 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)

setNamespaceMappings

public void setNamespaceMappings(Map<String,String> namespaceMappings)
Set the namespace mappings. Property names are interpreted as namespace prefixes; values are namespace URIs.

See Also:
Marshaller.setNamespaceMapping(String, String)

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)

afterPropertiesSet

public final void afterPropertiesSet()
                              throws CastorMappingException,
                                     IOException
Description copied from interface: InitializingBean
Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).

This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.

Specified by:
afterPropertiesSet in interface InitializingBean
Throws:
CastorMappingException
IOException

createXMLContext

protected org.exolab.castor.xml.XMLContext createXMLContext(Resource[] mappingLocations,
                                                            Class[] targetClasses,
                                                            String[] targetPackages)
                                                     throws org.exolab.castor.mapping.MappingException,
                                                            org.exolab.castor.xml.ResolverException,
                                                            IOException
Create the Castor XMLContext. Subclasses can override this to create a custom context.

The default implementation loads mapping files if defined, or the target class or packages if defined.

Returns:
the created resolver
Throws:
org.exolab.castor.mapping.MappingException - when the mapping file cannot be loaded
IOException - in case of I/O errors
org.exolab.castor.xml.ResolverException
See Also:
XMLContext.addMapping(org.exolab.castor.mapping.Mapping), XMLContext.addClass(Class)

supports

public boolean supports(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

marshalDomNode

protected final void marshalDomNode(Object graph,
                                    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(Object graph,
                                        ContentHandler contentHandler,
                                        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(Object graph,
                                         OutputStream outputStream)
                                  throws XmlMappingException,
                                         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
IOException - if an I/O exception occurs

marshalWriter

protected final void marshalWriter(Object graph,
                                   Writer writer)
                            throws XmlMappingException,
                                   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
IOException - if an I/O exception occurs

marshalXmlEventWriter

protected final void marshalXmlEventWriter(Object graph,
                                           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(Object graph,
                                            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.

The 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 Object unmarshalDomNode(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 Object unmarshalInputStream(InputStream inputStream)
                                     throws XmlMappingException,
                                            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
IOException - if an I/O exception occurs

unmarshalReader

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

unmarshalXmlEventReader

protected final Object unmarshalXmlEventReader(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 Object unmarshalSaxReader(XMLReader xmlReader,
                                          InputSource inputSource)
                                   throws XmlMappingException,
                                          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
IOException - if an I/O exception occurs

unmarshalXmlStreamReader

protected final Object unmarshalXmlStreamReader(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.

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


convertCastorException

protected XmlMappingException convertCastorException(org.exolab.castor.xml.XMLException ex,
                                                     boolean marshalling)
Convert the given XMLException to an appropriate exception from the org.springframework.oxm hierarchy.

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