CastorMarshaller (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.oxm.castor

## Class CastorMarshaller

- java.lang.Object
- - org.springframework.oxm.support.AbstractMarshaller
  - - org.springframework.oxm.castor.CastorMarshaller

- All Implemented Interfaces:
    Aware, BeanClassLoaderAware, InitializingBean, Marshaller, Unmarshaller

      public class CastorMarshaller
      extends AbstractMarshaller
      implements InitializingBean, BeanClassLoaderAware

  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 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`.

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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Constructor and Description
    `CastorMarshaller()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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` | `setBeanClassLoader(ClassLoader classLoader)` Callback that supplies the bean `class loader` to a bean instance.
    `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(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` | `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`.

    - ### 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.

    - #### setTargetPackage

          public void setTargetPackage(String targetPackage)

      Set the names of package with the Castor descriptor classes.

    - #### setTargetPackages

          public void setTargetPackages(String[] targetPackages)

      Set the 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)`

    - #### setMarshalAsDocument

          public void setMarshalAsDocument(boolean marshalAsDocument)

      Sets whether this marshaller should output the xml declaration. The default is `true`, the xml declaration will be written.
      See Also:
        `Marshaller.setMarshalAsDocument(boolean)`

    - #### setRootElement

          public void setRootElement(String rootElement)

      Sets the name of the root element.
      See Also:
        `Marshaller.setRootElement(String)`

    - #### setMarshalExtendedType

          public void setMarshalExtendedType(boolean marshalExtendedType)

      Sets whether this marshaller should output for given type the `xsi:type` attribute. The default is `true`, the `xsi:type` attribute will be written.
      See Also:
        `Marshaller.setMarshalExtendedType(boolean)`

    - #### setNoNamespaceSchemaLocation

          public void setNoNamespaceSchemaLocation(String noNamespaceSchemaLocation)

      Sets the value of `xsi:noNamespaceSchemaLocation` attribute. When set, the `xsi:noNamespaceSchemaLocation` attribute will be written for the root element.
      See Also:
        `Marshaller.setNoNamespaceSchemaLocation(String)`

    - #### setSchemaLocation

          public void setSchemaLocation(String schemaLocation)

      Sets the value of `xsi:schemaLocation` attribute.When set, the `xsi:schemaLocation` attribute will be written for the root element.
      See Also:
        `Marshaller.setSchemaLocation(String)`

    - #### setUseXSITypeAtRoot

          public void setUseXSITypeAtRoot(boolean useXSITypeAtRoot)

      Sets whether this marshaller should output the `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.
      See Also:
        `Marshaller.setUseXSITypeAtRoot(boolean)`

    - #### setProcessingInstructions

          public void setProcessingInstructions(Map<String,String> processingInstructions)

      Sets the processing instructions that will be used by during marshalling. Keys are the processing targets and values contain the processing data.
      See Also:
        `Marshaller.addProcessingInstruction(String, String)`

    - #### setNamespaceToPackageMapping

          public void setNamespaceToPackageMapping(Map<String,String> namespaceToPackageMapping)

      Set the namespace to package mappings. Property names are represents the namespaces URI, values are packages.
      See Also:
        `Marshaller.setNamespaceMapping(String, String)`

    - #### setObject

          public void setObject(Object root)

      Sets the expected object for the unmarshaller, into which the source will be unmarshalled.
      See Also:
        `Unmarshaller.setObject(Object)`

    - #### setReuseObjects

          public void setReuseObjects(boolean reuseObjects)

      Sets whether this unmarshaller should re-use objects. This will be only used when unmarshalling to existing object. The default is `false`, which means that the objects won't be re-used.
      See Also:
        `Unmarshaller.setReuseObjects(boolean)`

    - #### setClearCollections

          public void setClearCollections(boolean clearCollections)

      Sets whether this unmarshaller should clear collections upon the first use. The default is `false`, which means that marshaller won't clear collections.
      See Also:
        `Unmarshaller.setClearCollections(boolean)`

    - #### setBeanClassLoader

          public void setBeanClassLoader(ClassLoader classLoader)

      Description copied from interface: `BeanClassLoaderAware`
      Callback that supplies the bean `class loader` to a bean instance.

      Invoked after the population of normal bean properties but before an initialization callback such as `InitializingBean's` `InitializingBean.afterPropertiesSet()` method or a custom init-method.

      Specified by:
        `setBeanClassLoader` in interface `BeanClassLoaderAware`
      Parameters:
        `classLoader` - the owning class loader; may be `null` in which case a default `ClassLoader` must be used, for example the `ClassLoader` obtained via `ClassUtils.getDefaultClassLoader()`

    - #### 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
      1. `Marshaller.setValidation(boolean)`,
      2. `Marshaller.setSuppressNamespaces(boolean)`,
      3. `Marshaller.setSuppressXSIType(boolean)`,
      4. `Marshaller.setMarshalAsDocument(boolean)`,
      5. `Marshaller.setRootElement(String)`,
      6. `Marshaller.setMarshalExtendedType(boolean)`,
      7. `Marshaller.setNoNamespaceSchemaLocation(String)`,
      8. `Marshaller.setSchemaLocation(String)` and
      9. `Marshaller.setUseXSITypeAtRoot(boolean)`.
      with the property set on this marshaller. It also calls `Marshaller.setNamespaceMapping(String, String)` with the namespace mappings and `Marshaller.addProcessingInstruction(String, String)` with the processing instructions.

    - #### 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

    - #### 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

    - #### 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

    - #### 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
      1. `Unmarshaller.setValidation(boolean)`,
      2. `Unmarshaller.setWhitespacePreserve(boolean)`,
      3. `Unmarshaller.setIgnoreExtraAttributes(boolean)`,
      4. `Unmarshaller.setIgnoreExtraElements(boolean)`,
      5. `Unmarshaller.setClassLoader(ClassLoader)`,
      6. `Unmarshaller.setObject(Object)`,
      7. `Unmarshaller.setReuseObjects(boolean)` and
      8. `Unmarshaller.setClearCollections(boolean)`
      with the properties set on this marshaller. It also calls `Unmarshaller.addNamespaceToPackageMapping(String, String)` with the namespace to package mapping.

    - #### 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 occurred
        `marshalling` - indicates whether the exception occurs during marshalling (`true`), or unmarshalling (`false`)
      Returns:
        the corresponding `XmlMappingException`