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 . |
protected String |
getDefaultEncoding()
Determine the default encoding to use for marshalling or unmarshalling from
a byte stream, or
null if none. |
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 |
setCastorProperties(Map<String,String> castorProperties)
Set Castor-specific properties for marshalling and unmarshalling.
|
void |
setClassDescriptorResolver(org.exolab.castor.xml.XMLClassDescriptorResolver classDescriptorResolver)
Set the
XMLClassDescriptorResolver to be used during unmarshalling. |
void |
setClearCollections(boolean clearCollections)
Sets whether this unmarshaller should clear collections upon the first use.
|
void |
setDoctypes(Map<String,String> doctypes)
Set the map containing document type definition for the marshaller.
|
void |
setEncoding(String encoding)
Set the encoding to be used for stream access.
|
void |
setEntityResolver(EntityResolver entityResolver)
Set the
EntityResolver to be used during unmarshalling. |
void |
setIdResolver(org.exolab.castor.xml.IDResolver idResolver)
Set the Castor
IDResolver to be used during unmarshalling. |
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)
Set whether this marshaller should output the xml declaration.
|
void |
setMarshalExtendedType(boolean marshalExtendedType)
Set 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)
Set the value of
xsi:noNamespaceSchemaLocation attribute. |
void |
setObject(Object root)
Deprecated.
in favor of
setRootObject(java.lang.Object) |
void |
setObjectFactory(org.exolab.castor.util.ObjectFactory objectFactory)
Set the Castor
ObjectFactory to be used during unmarshalling. |
void |
setProcessingInstructions(Map<String,String> processingInstructions)
Sets the processing instructions that will be used by during marshalling.
|
void |
setReuseObjects(boolean reuseObjects)
Set whether this unmarshaller should re-use objects.
|
void |
setRootElement(String rootElement)
Set the name of the root element.
|
void |
setRootObject(Object root)
Set the expected root object for the unmarshaller, into which the source will be unmarshalled.
|
void |
setSchemaLocation(String schemaLocation)
Set the value of
xsi:schemaLocation attribute. |
void |
setSuppressNamespaces(boolean suppressNamespaces)
Sets whether this marshaller should output namespaces.
|
void |
setSuppressXsiType(boolean suppressXsiType)
Set 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 name of a 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 . |
buildDocument, createDocumentBuilder, createDocumentBuilderFactory, createXmlReader, isProcessExternalEntities, marshal, marshalDomResult, marshalSaxResult, marshalStaxResult, marshalStreamResult, setProcessExternalEntities, unmarshal, unmarshalDomSource, unmarshalSaxSource, unmarshalStaxSource, unmarshalStreamSource
public static final String DEFAULT_ENCODING
public void setEncoding(String encoding)
DEFAULT_ENCODING
protected String getDefaultEncoding()
AbstractMarshaller
null
if none.
The default implementation returns null
.
getDefaultEncoding
in class AbstractMarshaller
public void setMappingLocation(org.springframework.core.io.Resource mappingLocation)
public void setMappingLocations(org.springframework.core.io.Resource... mappingLocations)
public void setTargetClass(Class<?> targetClass)
public void setTargetClasses(Class<?>... targetClasses)
public void setTargetPackage(String targetPackage)
public void setTargetPackages(String... targetPackages)
public void setValidating(boolean validating)
Default is false
.
Marshaller.setValidation(boolean)
public void setSuppressNamespaces(boolean suppressNamespaces)
The default is false
, i.e. namespaces are written.
Marshaller.setSuppressNamespaces(boolean)
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)
The default is true
, the XML declaration will be written.
Marshaller.setMarshalAsDocument(boolean)
public void setMarshalExtendedType(boolean marshalExtendedType)
xsi:type
attribute.
The default is true
, the xsi:type
attribute will be written.
Marshaller.setMarshalExtendedType(boolean)
public void setRootElement(String rootElement)
Marshaller.setRootElement(String)
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 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 elements are flagged as an error.
Unmarshaller.setIgnoreExtraElements(boolean)
@Deprecated public void setObject(Object root)
setRootObject(java.lang.Object)
Unmarshaller.setObject(Object)
public void setRootObject(Object root)
Unmarshaller.setObject(Object)
public void setReuseObjects(boolean reuseObjects)
The default is false
, which means that the objects won't be re-used.
Unmarshaller.setReuseObjects(boolean)
public void setClearCollections(boolean clearCollections)
The default is false
which means that marshaller won't clear collections.
Unmarshaller.setClearCollections(boolean)
public void setCastorProperties(Map<String,String> castorProperties)
Marshaller.setProperty(String, String)
,
Unmarshaller.setProperty(String, String)
public void setDoctypes(Map<String,String> doctypes)
Marshaller.setDoctype(String, String)
public void setProcessingInstructions(Map<String,String> processingInstructions)
Marshaller.addProcessingInstruction(String, String)
public void setNamespaceMappings(Map<String,String> namespaceMappings)
Marshaller.setNamespaceMapping(String, String)
public void setNamespaceToPackageMapping(Map<String,String> namespaceToPackageMapping)
Marshaller.setNamespaceMapping(String, String)
public void setEntityResolver(EntityResolver entityResolver)
EntityResolver
to be used during unmarshalling.
This resolver will used to resolve system and public ids.Unmarshaller.setEntityResolver(EntityResolver)
public void setClassDescriptorResolver(org.exolab.castor.xml.XMLClassDescriptorResolver classDescriptorResolver)
XMLClassDescriptorResolver
to be used during unmarshalling.
This resolver will used to resolve class descriptors.Unmarshaller.setResolver(XMLClassDescriptorResolver)
public void setIdResolver(org.exolab.castor.xml.IDResolver idResolver)
IDResolver
to be used during unmarshalling.Unmarshaller.setIDResolver(IDResolver)
public void setObjectFactory(org.exolab.castor.util.ObjectFactory objectFactory)
ObjectFactory
to be used during unmarshalling.Unmarshaller.setObjectFactory(ObjectFactory)
public void setBeanClassLoader(ClassLoader classLoader)
setBeanClassLoader
in interface org.springframework.beans.factory.BeanClassLoaderAware
public 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 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 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 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 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 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 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 void customizeMarshaller(org.exolab.castor.xml.Marshaller marshaller)
Marshaller
.protected 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 Object unmarshalXmlEventReader(XMLEventReader eventReader)
AbstractMarshaller
XMLEventReader
.unmarshalXmlEventReader
in class AbstractMarshaller
eventReader
- the XMLEventReader
to read fromprotected Object unmarshalXmlStreamReader(XMLStreamReader streamReader)
AbstractMarshaller
XMLStreamReader
.unmarshalXmlStreamReader
in class AbstractMarshaller
streamReader
- the XMLStreamReader
to read fromprotected 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 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 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 void customizeUnmarshaller(org.exolab.castor.xml.Unmarshaller unmarshaller)
Unmarshaller
.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