public class CastorMarshaller extends AbstractMarshaller implements org.springframework.beans.factory.InitializingBean, org.springframework.beans.factory.BeanClassLoaderAware
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 unmarshal XML that represents that specific class. If you want to unmarshal 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
.
setEncoding(String)
,
setTargetClass(Class)
,
setTargetPackages(String[])
,
setMappingLocation(Resource)
,
setMappingLocations(Resource[])
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_ENCODING
The default encoding used for stream access: UTF-8.
|
logger
Constructor and Description |
---|
CastorMarshaller() |
Modifier and Type | Method and Description |
---|---|
void |
afterPropertiesSet() |
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(org.springframework.core.io.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 |
setBeanClassLoader(ClassLoader classLoader) |
void |
setClearCollections(boolean clearCollections)
Sets whether this unmarshaller should clear collections upon the first use.
|
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(org.springframework.core.io.Resource mappingLocation)
Set the locations of the Castor XML Mapping files.
|
void |
setMappingLocations(org.springframework.core.io.Resource[] mappingLocations)
Set the locations of the Castor XML Mapping files.
|
void |
setMarshalAsDocument(boolean marshalAsDocument)
Sets whether this marshaller should output the xml declaration.
|
void |
setMarshalExtendedType(boolean marshalExtendedType)
Sets whether this marshaller should output for given type the
xsi:type attribute. |
void |
setNamespaceMappings(Map<String,String> namespaceMappings)
Set the namespace mappings.
|
void |
setNamespaceToPackageMapping(Map<String,String> namespaceToPackageMapping)
Set the namespace to package mappings.
|
void |
setNoNamespaceSchemaLocation(String noNamespaceSchemaLocation)
Sets the value of
xsi:noNamespaceSchemaLocation attribute. |
void |
setObject(Object root)
Sets the expected object for the unmarshaller, into which the source will be unmarshalled.
|
void |
setProcessingInstructions(Map<String,String> processingInstructions)
Sets the processing instructions that will be used by during marshalling.
|
void |
setReuseObjects(boolean reuseObjects)
Sets whether this unmarshaller should re-use objects.
|
void |
setRootElement(String rootElement)
Sets the name of the root element.
|
void |
setSchemaLocation(String schemaLocation)
Sets the value of
xsi:schemaLocation attribute.When set, the xsi:schemaLocation attribute will be
written for the root element. |
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 |
setTargetPackage(String targetPackage)
Set the names of package with the Castor descriptor classes.
|
void |
setTargetPackages(String[] targetPackages)
Set the names of packages with the Castor descriptor classes.
|
void |
setUseXSITypeAtRoot(boolean useXSITypeAtRoot)
Sets whether this marshaller should output the
xsi:type attribute for the root element. |
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 . |
createDocumentBuilder, createDocumentBuilderFactory, createXmlReader, marshal, marshalDomResult, marshalSaxResult, marshalStaxResult, marshalStreamResult, unmarshal, unmarshalDomSource, unmarshalSaxSource, unmarshalStaxSource, unmarshalStreamSource
public static final String DEFAULT_ENCODING
public void setEncoding(String encoding)
DEFAULT_ENCODING
public void setMappingLocation(org.springframework.core.io.Resource mappingLocation)
public void setMappingLocations(org.springframework.core.io.Resource[] mappingLocations)
public void setTargetClass(Class targetClass)
CastorMarshaller
for unmarshalling
multiple classes include use of mapping files, and specifying packages with Castor descriptor classes.public void setTargetClasses(Class[] targetClasses)
CastorMarshaller
for unmarshalling
multiple classes include use of mapping files, and specifying packages with Castor descriptor classes.public void setTargetPackage(String targetPackage)
public void setTargetPackages(String[] targetPackages)
public void setValidating(boolean validating)
Default is false
.
Marshaller.setValidation(boolean)
public void setWhitespacePreserve(boolean whitespacePreserve)
Unmarshaller
should preserve "ignorable" whitespace. Default is
false
.
Unmarshaller.setWhitespacePreserve(boolean)
public void setIgnoreExtraAttributes(boolean ignoreExtraAttributes)
Unmarshaller
should ignore attributes that do not match a specific field. Default
is true
: extra attributes are ignored.
Unmarshaller.setIgnoreExtraAttributes(boolean)
public void setIgnoreExtraElements(boolean ignoreExtraElements)
Unmarshaller
should ignore elements that do not match a specific field. Default
is
false
, extra attributes are flagged as an error.
Unmarshaller.setIgnoreExtraElements(boolean)
public void setNamespaceMappings(Map<String,String> namespaceMappings)
Marshaller.setNamespaceMapping(String, String)
public boolean isSuppressNamespaces()
public void setSuppressNamespaces(boolean suppressNamespaces)
false
, i.e. namespaces are written.Marshaller.setSuppressNamespaces(boolean)
public boolean isSuppressXsiType()
public void setSuppressXsiType(boolean suppressXsiType)
xsi:type
attribute. The default is false
, i.e. the
xsi:type
is written.Marshaller.setSuppressXSIType(boolean)
public void setMarshalAsDocument(boolean marshalAsDocument)
true
, the xml
declaration will be written.Marshaller.setMarshalAsDocument(boolean)
public void setRootElement(String rootElement)
Marshaller.setRootElement(String)
public void setMarshalExtendedType(boolean marshalExtendedType)
xsi:type
attribute. The default is true
, the xsi:type
attribute will be written.Marshaller.setMarshalExtendedType(boolean)
public void setNoNamespaceSchemaLocation(String noNamespaceSchemaLocation)
xsi:noNamespaceSchemaLocation
attribute. When set, the xsi:noNamespaceSchemaLocation
attribute will be written for the root element.Marshaller.setNoNamespaceSchemaLocation(String)
public void setSchemaLocation(String schemaLocation)
xsi:schemaLocation
attribute.When set, the xsi:schemaLocation
attribute will be
written for the root element.Marshaller.setSchemaLocation(String)
public void setUseXSITypeAtRoot(boolean useXSITypeAtRoot)
xsi:type
attribute for the root element. This can be useful
when the type of the element can not be simply determined from the element name. The default is false
,
the xsi:type
attribute for the root element won't be written.Marshaller.setUseXSITypeAtRoot(boolean)
public void setProcessingInstructions(Map<String,String> processingInstructions)
Marshaller.addProcessingInstruction(String, String)
public void setNamespaceToPackageMapping(Map<String,String> namespaceToPackageMapping)
Marshaller.setNamespaceMapping(String, String)
public void setObject(Object root)
Unmarshaller.setObject(Object)
public void setReuseObjects(boolean reuseObjects)
false
, which means that the objects won't be re-used.Unmarshaller.setReuseObjects(boolean)
public void setClearCollections(boolean clearCollections)
false
,
which means that marshaller won't clear collections.Unmarshaller.setClearCollections(boolean)
public void setBeanClassLoader(ClassLoader classLoader)
setBeanClassLoader
in interface org.springframework.beans.factory.BeanClassLoaderAware
public final void afterPropertiesSet() throws CastorMappingException, IOException
afterPropertiesSet
in interface org.springframework.beans.factory.InitializingBean
CastorMappingException
IOException
protected org.exolab.castor.xml.XMLContext createXMLContext(org.springframework.core.io.Resource[] mappingLocations, Class[] targetClasses, String[] targetPackages) throws org.exolab.castor.mapping.MappingException, org.exolab.castor.xml.ResolverException, IOException
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.
org.exolab.castor.mapping.MappingException
- when the mapping file cannot be loadedIOException
- in case of I/O errorsorg.exolab.castor.xml.ResolverException
XMLContext.addMapping(org.exolab.castor.mapping.Mapping)
,
XMLContext.addClass(Class)
public boolean supports(Class<?> clazz)
true
for all classes, i.e. Castor supports arbitrary classes.supports
in interface Marshaller
supports
in interface Unmarshaller
clazz
- the class that this marshaller is being asked if it can marshaltrue
if this marshaller can indeed marshal instances of the supplied class;
false
otherwiseprotected final void marshalDomNode(Object graph, Node node) throws XmlMappingException
AbstractMarshaller
Node
.
In practice, node is be a Document
node, a DocumentFragment
node,
or a Element
node. In other words, a node that accepts children.
marshalDomNode
in class AbstractMarshaller
graph
- the root of the object graph to marshalnode
- the DOM node that will contain the result treeXmlMappingException
- if the given object cannot be marshalled to the DOM nodeDocument
,
DocumentFragment
,
Element
protected final void marshalSaxHandlers(Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler) throws XmlMappingException
AbstractMarshaller
ContentHandler
.marshalSaxHandlers
in class AbstractMarshaller
graph
- the root of the object graph to marshalcontentHandler
- the SAX ContentHandler
lexicalHandler
- the SAX2 LexicalHandler
. Can be null
.XmlMappingException
- if the given object cannot be marshalled to the handlersprotected final void marshalOutputStream(Object graph, OutputStream outputStream) throws XmlMappingException, IOException
AbstractMarshaller
OutputStream
.marshalOutputStream
in class AbstractMarshaller
graph
- the root of the object graph to marshaloutputStream
- the OutputStream
to write toXmlMappingException
- if the given object cannot be marshalled to the writerIOException
- if an I/O exception occursprotected final void marshalWriter(Object graph, Writer writer) throws XmlMappingException, IOException
AbstractMarshaller
Writer
.marshalWriter
in class AbstractMarshaller
graph
- the root of the object graph to marshalwriter
- the Writer
to write toXmlMappingException
- if the given object cannot be marshalled to the writerIOException
- if an I/O exception occursprotected final void marshalXmlEventWriter(Object graph, XMLEventWriter eventWriter) throws XmlMappingException
AbstractMarshaller
XMLEventWriter
.marshalXmlEventWriter
in class AbstractMarshaller
graph
- the root of the object graph to marshaleventWriter
- the XMLEventWriter
to write toXmlMappingException
- if the given object cannot be marshalled to the DOM nodeprotected final void marshalXmlStreamWriter(Object graph, XMLStreamWriter streamWriter) throws XmlMappingException
AbstractMarshaller
XMLStreamWriter
.marshalXmlStreamWriter
in class AbstractMarshaller
graph
- the root of the object graph to marshalstreamWriter
- the XMLStreamWriter
to write toXmlMappingException
- if the given object cannot be marshalled to the DOM nodeprotected void customizeMarshaller(org.exolab.castor.xml.Marshaller marshaller)
Marshaller
.
The default implementation invokes
Marshaller.setValidation(boolean)
,Marshaller.setSuppressNamespaces(boolean)
,Marshaller.setSuppressXSIType(boolean)
, Marshaller.setMarshalAsDocument(boolean)
, Marshaller.setRootElement(String)
,Marshaller.setMarshalExtendedType(boolean)
,Marshaller.setNoNamespaceSchemaLocation(String)
,Marshaller.setSchemaLocation(String)
andMarshaller.setUseXSITypeAtRoot(boolean)
.Marshaller.setNamespaceMapping(String, String)
with the namespace mappings and
Marshaller.addProcessingInstruction(String, String)
with the
processing instructions.protected final Object unmarshalDomNode(Node node) throws XmlMappingException
AbstractMarshaller
Node
.unmarshalDomNode
in class AbstractMarshaller
node
- the DOM node that contains the objects to be unmarshalledXmlMappingException
- if the given DOM node cannot be mapped to an objectprotected final Object unmarshalInputStream(InputStream inputStream) throws XmlMappingException, IOException
AbstractMarshaller
InputStream
.unmarshalInputStream
in class AbstractMarshaller
inputStream
- the InputStreamStream
to read fromXmlMappingException
- if the given stream cannot be converted to an objectIOException
- if an I/O exception occursprotected final Object unmarshalReader(Reader reader) throws XmlMappingException, IOException
AbstractMarshaller
Reader
.unmarshalReader
in class AbstractMarshaller
reader
- the Reader
to read fromXmlMappingException
- if the given reader cannot be converted to an objectIOException
- if an I/O exception occursprotected final Object unmarshalSaxReader(XMLReader xmlReader, InputSource inputSource) throws XmlMappingException, IOException
AbstractMarshaller
XMLReader
and InputSource
.unmarshalSaxReader
in class AbstractMarshaller
xmlReader
- the SAX XMLReader
to parse withinputSource
- the input source to parse fromXmlMappingException
- if the given reader and input source cannot be converted to an objectIOException
- if an I/O exception occursprotected final Object unmarshalXmlEventReader(XMLEventReader eventReader)
AbstractMarshaller
XMLEventReader
.unmarshalXmlEventReader
in class AbstractMarshaller
eventReader
- the XMLEventReader
to read fromprotected final Object unmarshalXmlStreamReader(XMLStreamReader streamReader)
AbstractMarshaller
XMLStreamReader
.unmarshalXmlStreamReader
in class AbstractMarshaller
streamReader
- the XMLStreamReader
to read fromprotected void customizeUnmarshaller(org.exolab.castor.xml.Unmarshaller unmarshaller)
Unmarshaller
.
The default implementation invokes
Unmarshaller.setValidation(boolean)
,
Unmarshaller.setWhitespacePreserve(boolean)
,
Unmarshaller.setIgnoreExtraAttributes(boolean)
,
Unmarshaller.setIgnoreExtraElements(boolean)
,
Unmarshaller.setClassLoader(ClassLoader)
,
Unmarshaller.setObject(Object)
,
Unmarshaller.setReuseObjects(boolean)
and
Unmarshaller.setClearCollections(boolean)
Unmarshaller.addNamespaceToPackageMapping(String, String)
with the
namespace to package mapping.protected XmlMappingException convertCastorException(org.exolab.castor.xml.XMLException ex, boolean marshalling)
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.
ex
- Castor XMLException
that occurredmarshalling
- indicates whether the exception occurs during marshalling (true
), or unmarshalling
(false
)XmlMappingException