## org.springframework.oxm.castor
Class CastorMarshaller

    java.lang.Object
      org.springframework.oxm.support.AbstractMarshaller
          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`