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

org.springframework.oxm.jibx

## Class JibxMarshaller

- java.lang.Object
- - org.springframework.oxm.support.AbstractMarshaller
  - - org.springframework.oxm.jibx.JibxMarshaller

- All Implemented Interfaces:
    InitializingBean, Marshaller, Unmarshaller

      public class JibxMarshaller
      extends AbstractMarshaller
      implements InitializingBean

  Implementation of the `Marshaller` and `Unmarshaller` interfaces for JiBX.

  The typical usage will be to set the `targetClass` and optionally the `bindingName` property on this bean.

  Since:
    3.0
  Author:
    Arjen Poutsma
  See Also:
    `IMarshallingContext`, `IUnmarshallingContext`

- - ### Field Summary

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

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JibxMarshaller()`

  - ### 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).
    `XmlMappingException` | `convertJibxException(org.jibx.runtime.JiBXException ex, boolean marshalling)` Convert the given `JiBXException` to an appropriate exception from the `org.springframework.oxm` hierarchy.
    `protected org.jibx.runtime.IMarshallingContext` | `createMarshallingContext()` Create a new `IMarshallingContext`, configured with the correct indentation.
    `protected org.jibx.runtime.IUnmarshallingContext` | `createUnmarshallingContext()` Create a new `IUnmarshallingContext`.
    `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` | `setBindingName(String bindingName)` Set the optional binding name for this instance.
    `void` | `setDocTypeInternalSubset(String docTypeInternalSubset)` Sets the internal subset Id for the DTD declaration written when marshalling.
    `void` | `setDocTypePublicId(String docTypePublicId)` Sets the public Id for the DTD declaration written when marshalling.
    `void` | `setDocTypeRootElementName(String docTypeRootElementName)` Sets the root element name for the DTD declaration written when marshalling.
    `void` | `setDocTypeSystemId(String docTypeSystemId)` Sets the system Id for the DTD declaration written when marshalling.
    `void` | `setEncoding(String encoding)` Set the document encoding using for marshalling.
    `void` | `setIndent(int indent)` Set the number of nesting indent spaces.
    `void` | `setStandalone(Boolean standalone)` Set the document standalone flag for marshalling.
    `void` | `setTargetClass(Class<?> targetClass)` Set the target class for this instance.
    `void` | `setTargetPackage(String targetPackage)` Set the target package for this instance.
    `boolean` | `supports(Class<?> clazz)` Indicates whether this marshaller can marshal instances of the supplied type.
    `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`

- - ### Constructor Detail

    - #### JibxMarshaller

          public JibxMarshaller()

  - ### Method Detail

    - #### setTargetClass

          public void setTargetClass(Class<?> targetClass)

      Set the target class for this instance. Setting either this property or the `targetPackage` property is required.

      If this property is set, `targetPackage` is ignored.

    - #### setTargetPackage

          public void setTargetPackage(String targetPackage)

      Set the target package for this instance. Setting either this property or the `targetClass` property is required.

      If `targetClass` is set, this property is ignored.

    - #### setBindingName

          public void setBindingName(String bindingName)

      Set the optional binding name for this instance.

    - #### setIndent

          public void setIndent(int indent)

      Set the number of nesting indent spaces. Default is `-1`, i.e. no indentation.

    - #### setEncoding

          public void setEncoding(String encoding)

      Set the document encoding using for marshalling. Default is UTF-8.

    - #### setStandalone

          public void setStandalone(Boolean standalone)

      Set the document standalone flag for marshalling. By default, this flag is not present.

    - #### setDocTypeRootElementName

          public void setDocTypeRootElementName(String docTypeRootElementName)

      Sets the root element name for the DTD declaration written when marshalling. By default, this is `null` (i.e. no DTD declaration is written). If set to a value, the system ID or public ID also need to be set.
      See Also:
        `setDocTypeSystemId(String)`, `setDocTypePublicId(String)`

    - #### setDocTypeSystemId

          public void setDocTypeSystemId(String docTypeSystemId)

      Sets the system Id for the DTD declaration written when marshalling. By default, this is `null`. Only used when the root element also has been set. Set either this property or `docTypePublicId`, not both.
      See Also:
        `setDocTypeRootElementName(String)`

    - #### setDocTypePublicId

          public void setDocTypePublicId(String docTypePublicId)

      Sets the public Id for the DTD declaration written when marshalling. By default, this is `null`. Only used when the root element also has been set. Set either this property or `docTypeSystemId`, not both.
      See Also:
        `setDocTypeRootElementName(String)`

    - #### setDocTypeInternalSubset

          public void setDocTypeInternalSubset(String docTypeInternalSubset)

      Sets the internal subset Id for the DTD declaration written when marshalling. By default, this is `null`. Only used when the root element also has been set.
      See Also:
        `setDocTypeRootElementName(String)`

    - #### afterPropertiesSet

          public void afterPropertiesSet()
                                  throws org.jibx.runtime.JiBXException

      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:
        `org.jibx.runtime.JiBXException`

    - #### supports

          public boolean supports(Class<?> clazz)

      Description copied from interface: `Marshaller`
      Indicates whether this marshaller can marshal instances of the supplied type.
      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

    - #### marshalOutputStream

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

    - #### marshalXmlStreamWriter

          protected 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

    - #### marshalDomNode

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

    - #### marshalXmlEventWriter

          protected 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

    - #### unmarshalInputStream

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

    - #### unmarshalXmlStreamReader

          protected 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

    - #### unmarshalXmlEventReader

          protected 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

    - #### unmarshalDomNode

          protected 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

    - #### unmarshalSaxReader

          protected 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

    - #### createMarshallingContext

          protected org.jibx.runtime.IMarshallingContext createMarshallingContext()
                                                                           throws org.jibx.runtime.JiBXException

      Create a new `IMarshallingContext`, configured with the correct indentation.
      Returns:
        the created marshalling context
      Throws:
        `org.jibx.runtime.JiBXException` - in case of errors

    - #### createUnmarshallingContext

          protected org.jibx.runtime.IUnmarshallingContext createUnmarshallingContext()
                                                                               throws org.jibx.runtime.JiBXException

      Create a new `IUnmarshallingContext`.
      Returns:
        the created unmarshalling context
      Throws:
        `org.jibx.runtime.JiBXException` - in case of errors

    - #### convertJibxException

          public XmlMappingException convertJibxException(org.jibx.runtime.JiBXException ex,
                                                 boolean marshalling)

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

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