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

org.springframework.oxm.xmlbeans

## Class XmlBeansMarshaller

- java.lang.Object
- - org.springframework.oxm.support.AbstractMarshaller
  - - org.springframework.oxm.xmlbeans.XmlBeansMarshaller

- All Implemented Interfaces:
    Marshaller, Unmarshaller

      public class XmlBeansMarshaller
      extends AbstractMarshaller

  Implementation of the `Marshaller` interface for Apache XMLBeans.

  Options can be set by setting the `xmlOptions` property. The `XmlOptionsFactoryBean` is provided to easily set up an `XmlOptions` instance.

  Unmarshalled objects can be validated by setting the `validating` property, or by calling the `validate(XmlObject)` method directly. Invalid objects will result in an `ValidationFailureException`.

  NOTE: Due to the nature of XMLBeans, this marshaller requires all passed objects to be of type `XmlObject`.

  Since:
    3.0
  Author:
    Arjen Poutsma
  See Also:
    `setValidating(boolean)`, `setXmlOptions(org.apache.xmlbeans.XmlOptions)`, `XmlOptionsFactoryBean`

- - ### Field Summary

    - ### Fields inherited from class org.springframework.oxm.support.AbstractMarshaller

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XmlBeansMarshaller()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected XmlMappingException` | `convertXmlBeansException(Exception ex, boolean marshalling)` Convert the given XMLBeans exception to an appropriate exception from the `org.springframework.oxm` hierarchy.
    `org.apache.xmlbeans.XmlOptions` | `getXmlOptions()` Return the `XmlOptions`.
    `boolean` | `isValidating()` Return whether this marshaller should validate in- and outgoing documents.
    `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` | `setValidating(boolean validating)` Set whether this marshaller should validate in- and outgoing documents.
    `void` | `setXmlOptions(org.apache.xmlbeans.XmlOptions xmlOptions)` Set the `XmlOptions`.
    `boolean` | `supports(Class<?> clazz)` This implementation returns true if the given class is an implementation of `XmlObject`.
    `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`.
    `protected void` | `validate(org.apache.xmlbeans.XmlObject object)` Validate the given `XmlObject`.

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

- - ### Constructor Detail

    - #### XmlBeansMarshaller

          public XmlBeansMarshaller()

  - ### Method Detail

    - #### setXmlOptions

          public void setXmlOptions(org.apache.xmlbeans.XmlOptions xmlOptions)

      Set the `XmlOptions`.
      See Also:
        `XmlOptionsFactoryBean`

    - #### getXmlOptions

          public org.apache.xmlbeans.XmlOptions getXmlOptions()

      Return the `XmlOptions`.

    - #### setValidating

          public void setValidating(boolean validating)

      Set whether this marshaller should validate in- and outgoing documents. Default is `false`.

    - #### isValidating

          public boolean isValidating()

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

    - #### supports

          public boolean supports(Class<?> clazz)

      This implementation returns true if the given class is an implementation of `XmlObject`.
      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`

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

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

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

      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

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

    - #### 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)
                                                  throws XmlMappingException

      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
      Throws:
        `XmlMappingException` - if the given event reader cannot be converted to an object

    - #### unmarshalXmlStreamReader

          protected final Object unmarshalXmlStreamReader(XMLStreamReader streamReader)
                                                   throws XmlMappingException

      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
      Throws:
        `XmlMappingException` - if the given stream reader cannot be converted to an object

    - #### validate

          protected void validate(org.apache.xmlbeans.XmlObject object)
                           throws ValidationFailureException

      Validate the given `XmlObject`.
      Parameters:
        `object` - the xml object to validate
      Throws:
        `ValidationFailureException` - if the given object is not valid

    - #### convertXmlBeansException

          protected XmlMappingException convertXmlBeansException(Exception ex,
                                                     boolean marshalling)

      Convert the given XMLBeans exception 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 XMLBeans itself does not make this distinction in its exception hierarchy.

      Parameters:
        `ex` - XMLBeans Exception that occured
        `marshalling` - indicates whether the exception occurs during marshalling (`true`), or unmarshalling (`false`)
      Returns:
        the corresponding `XmlMappingException`