public class

CastorMarshaller

extends AbstractMarshaller
implements InitializingBean
java.lang.Object
   ↳ org.springframework.oxm.support.AbstractMarshaller
     ↳ org.springframework.oxm.castor.CastorMarshaller

Class Overview

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.

See Also

Summary

Constants
String DEFAULT_ENCODING The default encoding used for stream access: UTF-8.
[Expand]
Inherited Fields
From class org.springframework.oxm.support.AbstractMarshaller
Public Constructors
CastorMarshaller()
Public Methods
final void afterPropertiesSet()
Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
boolean isSuppressNamespaces()
Returns whether this marshaller should output namespaces.
boolean isSuppressXsiType()
Sets whether this marshaller should output the xsi:type attribute.
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 Methods
XmlMappingException convertCastorException(XMLException ex, boolean marshalling)
Convert the given XMLException to an appropriate exception from the org.springframework.oxm hierarchy.
XMLContext createXMLContext(Resource[] mappingLocations, Class[] targetClasses, String[] targetPackages)
Create the Castor XMLContext.
void customizeMarshaller(Marshaller marshaller)
Template method that allows for customizing of the given Castor Marshaller.
void customizeUnmarshaller(Unmarshaller unmarshaller)
Template method that allows for customizing of the given Castor Unmarshaller.
final void marshalDomNode(Object graph, Node node)
Abstract template method for marshalling the given object graph to a DOM Node.
final void marshalOutputStream(Object graph, OutputStream outputStream)
Abstract template method for marshalling the given object graph to a OutputStream.
final void marshalSaxHandlers(Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler)
Abstract template method for marshalling the given object graph to a SAX ContentHandler.
final void marshalWriter(Object graph, Writer writer)
Abstract template method for marshalling the given object graph to a Writer.
final void marshalXmlEventWriter(Object graph, XMLEventWriter eventWriter)
Abstract template method for marshalling the given object to a StAX XMLEventWriter.
final void marshalXmlStreamWriter(Object graph, XMLStreamWriter streamWriter)
Abstract template method for marshalling the given object to a StAX XMLStreamWriter.
final Object unmarshalDomNode(Node node)
Abstract template method for unmarshalling from a given DOM Node.
final Object unmarshalInputStream(InputStream inputStream)
Abstract template method for unmarshalling from a given InputStream.
final Object unmarshalReader(Reader reader)
Abstract template method for unmarshalling from a given Reader.
final Object unmarshalSaxReader(XMLReader xmlReader, InputSource inputSource)
Abstract template method for unmarshalling using a given SAX XMLReader and InputSource.
final Object unmarshalXmlEventReader(XMLEventReader eventReader)
Abstract template method for unmarshalling from a given Stax XMLEventReader.
final Object unmarshalXmlStreamReader(XMLStreamReader streamReader)
Abstract template method for unmarshalling from a given Stax XMLStreamReader.
[Expand]
Inherited Methods
From class org.springframework.oxm.support.AbstractMarshaller
From class java.lang.Object
From interface org.springframework.beans.factory.InitializingBean
From interface org.springframework.oxm.Marshaller
From interface org.springframework.oxm.Unmarshaller

Constants

public static final String DEFAULT_ENCODING

The default encoding used for stream access: UTF-8.

Constant Value: "UTF-8"

Public Constructors

public CastorMarshaller ()

Public Methods

public final void afterPropertiesSet ()

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.

Throws
CastorMappingException
IOException

public boolean isSuppressNamespaces ()

Returns whether this marshaller should output namespaces.

public boolean isSuppressXsiType ()

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

public void setEncoding (String encoding)

Set the encoding to be used for stream access.

See Also

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
  • org.exolab.castor.xml.Unmarshaller#setIgnoreExtraAttributes(boolean)

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
  • org.exolab.castor.xml.Unmarshaller#setIgnoreExtraElements(boolean)

public void setMappingLocation (Resource mappingLocation)

Set the locations of the Castor XML Mapping files.

public void setMappingLocations (Resource[] mappingLocations)

Set the locations of the Castor XML Mapping files.

public void setNamespaceMappings (Map<String, String> namespaceMappings)

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

See Also
  • org.exolab.castor.xml.Marshaller#setNamespaceMapping(String, String)

public void setSuppressNamespaces (boolean suppressNamespaces)

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

See Also
  • org.exolab.castor.xml.Marshaller#setSuppressNamespaces(boolean)

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
  • org.exolab.castor.xml.Marshaller#setSuppressXSIType(boolean)

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.

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.

public void setTargetPackages (String[] targetPackages)

Set the package names of packages with the Castor descriptor classes.

public void setValidating (boolean validating)

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

Default is false.

See Also
  • Marshaller#setValidation(boolean)

public void setWhitespacePreserve (boolean whitespacePreserve)

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

Default is false.

See Also
  • org.exolab.castor.xml.Unmarshaller#setWhitespacePreserve(boolean)

public boolean supports (Class<?> clazz)

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

Protected Methods

protected XmlMappingException convertCastorException (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

protected XMLContext createXMLContext (Resource[] mappingLocations, Class[] targetClasses, String[] targetPackages)

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
when the mapping file cannot be loaded
IOException in case of I/O errors
MappingException
ResolverException
See Also
  • XMLContext#addMapping(org.exolab.castor.mapping.Mapping)
  • XMLContext#addClass(Class)

protected void customizeMarshaller (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.

protected void customizeUnmarshaller (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.

protected final void marshalDomNode (Object graph, Node node)

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

protected final void marshalOutputStream (Object graph, OutputStream outputStream)

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
IOException
XmlMappingException

protected final void marshalSaxHandlers (Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler)

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

protected final void marshalWriter (Object graph, Writer writer)

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
IOException
XmlMappingException

protected final void marshalXmlEventWriter (Object graph, XMLEventWriter eventWriter)

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

protected final void marshalXmlStreamWriter (Object graph, XMLStreamWriter streamWriter)

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

protected final Object unmarshalDomNode (Node node)

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

protected final Object unmarshalInputStream (InputStream inputStream)

Abstract template method for unmarshalling from a given InputStream.

Parameters
inputStream the InputStreamStream to read from
Returns
  • the object graph
Throws
IOException
XmlMappingException

protected final Object unmarshalReader (Reader reader)

Abstract template method for unmarshalling from a given Reader.

Parameters
reader the Reader to read from
Returns
  • the object graph
Throws
IOException
XmlMappingException

protected final Object unmarshalSaxReader (XMLReader xmlReader, InputSource inputSource)

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
IOException
XmlMappingException

protected final Object unmarshalXmlEventReader (XMLEventReader eventReader)

Abstract template method for unmarshalling from a given Stax XMLEventReader.

Parameters
eventReader the XMLEventReader to read from
Returns
  • the object graph

protected final Object unmarshalXmlStreamReader (XMLStreamReader streamReader)

Abstract template method for unmarshalling from a given Stax XMLStreamReader.

Parameters
streamReader the XMLStreamReader to read from
Returns
  • the object graph