org.springframework.batch.item.xml

## Class StaxEventItemWriter<T>

- java.lang.Object
- - org.springframework.batch.item.ItemStreamSupport
  - - org.springframework.batch.item.support.AbstractItemStreamItemWriter<T>
    - - org.springframework.batch.item.xml.StaxEventItemWriter<T>

- All Implemented Interfaces:
    ResourceAwareItemWriterItemStream<T>, ItemStream, ItemStreamWriter<T>, ItemWriter<T>, org.springframework.beans.factory.InitializingBean

      public class StaxEventItemWriter<T>
      extends AbstractItemStreamItemWriter<T>
      implements ResourceAwareItemWriterItemStream<T>, org.springframework.beans.factory.InitializingBean

  An implementation of `ItemWriter` which uses StAX and `Marshaller` for serializing object to XML. This item writer also provides restart, statistics and transaction features by implementing corresponding interfaces. The implementation is not thread-safe.
  Author:
    Peter Zozom, Robert Kasanicky, Michael Minella, Parikshit Dutta, Mahmoud Ben Hassine

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DEFAULT_ENCODING`
    `static java.lang.String` | `DEFAULT_ROOT_TAG_NAME`
    `static java.lang.Boolean` | `DEFAULT_STANDALONE_DOCUMENT`
    `static java.lang.String` | `DEFAULT_XML_VERSION`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StaxEventItemWriter()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()`
    `void` | `close()` Flush and close the output source.
    `protected javax.xml.transform.Result` | `createStaxResult()` Subclasses can override to customize the STAX result.
    `protected javax.xml.stream.XMLEventFactory` | `createXmlEventFactory()` Subclasses can override to customize the event factory.
    `protected javax.xml.stream.XMLEventWriter` | `createXmlEventWriter(javax.xml.stream.XMLOutputFactory outputFactory, java.io.Writer writer)` Subclasses can override to customize the writer.
    `protected javax.xml.stream.XMLOutputFactory` | `createXmlOutputFactory()` Subclasses can override to customize the factory.
    `protected void` | `endDocument(javax.xml.stream.XMLEventWriter writer)` Writes the EndDocument tag manually.
    `java.lang.String` | `getEncoding()` Get used encoding.
    `java.util.Map<java.lang.String,java.lang.String>` | `getRootElementAttributes()` Get attributes of the root element.
    `java.lang.String` | `getRootTagName()` Get the tag name of the root element.
    `java.lang.String` | `getRootTagNamespace()` Get the namespace of the root element.
    `java.lang.String` | `getRootTagNamespacePrefix()` Get the namespace prefix of the root element.
    `java.lang.Boolean` | `getStandalone()` Get used standalone document declaration.
    `java.lang.String` | `getVersion()` Get XML version.
    `protected void` | `initNamespaceContext(javax.xml.stream.XMLEventWriter writer)` Inits the namespace context of the XMLEventWriter: rootTagNamespacePrefix for rootTagName any other xmlns namespace prefix declarations in the root element attributes
    `void` | `open(ExecutionContext executionContext)` Open the output source
    `void` | `setEncoding(java.lang.String encoding)` Set encoding to be used for output file.
    `void` | `setFooterCallback(StaxWriterCallback footerCallback)` footerCallback is called after writing all items but before closing the file.
    `void` | `setForceSync(boolean forceSync)` Flag to indicate that changes should be force-synced to disk on flush.
    `void` | `setHeaderCallback(StaxWriterCallback headerCallback)` headerCallback is called before writing any items.
    `void` | `setMarshaller(org.springframework.oxm.Marshaller marshaller)` Set Object to XML marshaller.
    `void` | `setOverwriteOutput(boolean overwriteOutput)` Set "overwrite" flag for the output file.
    `void` | `setResource(org.springframework.core.io.Resource resource)` Set output file.
    `void` | `setRootElementAttributes(java.util.Map<java.lang.String,java.lang.String> rootElementAttributes)` Set the root element attributes to be written.
    `void` | `setRootTagName(java.lang.String rootTagName)` Set the tag name of the root element.
    `void` | `setSaveState(boolean saveState)`
    `void` | `setShouldDeleteIfEmpty(boolean shouldDeleteIfEmpty)` Flag to indicate that the target file should be deleted if no items have been written (other than header and footer) on close.
    `void` | `setStandalone(java.lang.Boolean standalone)` Set standalone document declaration to be used for output XML.
    `void` | `setTransactional(boolean transactional)` Flag to indicate that writes should be deferred to the end of a transaction if present.
    `void` | `setVersion(java.lang.String version)` Set XML version to be used for output XML.
    `protected void` | `startDocument(javax.xml.stream.XMLEventWriter writer)` Writes simple XML header containing: xml declaration - defines encoding and XML version opening tag of the root element and its attributes If this is not sufficient for you, simply override this method.
    `void` | `update(ExecutionContext executionContext)` Get the restart data.
    `void` | `write(java.util.List<? extends T> items)` Write the value objects and flush them to the file.

    - ### Methods inherited from class org.springframework.batch.item.ItemStreamSupport

      `getExecutionContextKey, setExecutionContextName, setName`

    - ### 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 java.lang.String DEFAULT_ENCODING

      See Also:
        Constant Field Values

    - #### DEFAULT_XML_VERSION

          public static final java.lang.String DEFAULT_XML_VERSION

      See Also:
        Constant Field Values

    - #### DEFAULT_STANDALONE_DOCUMENT

          public static final java.lang.Boolean DEFAULT_STANDALONE_DOCUMENT

    - #### DEFAULT_ROOT_TAG_NAME

          public static final java.lang.String DEFAULT_ROOT_TAG_NAME

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### StaxEventItemWriter

          public StaxEventItemWriter()

  - ### Method Detail

    - #### setResource

          public void setResource(org.springframework.core.io.Resource resource)

      Set output file.
      Specified by:
        `setResource` in interface `ResourceAwareItemWriterItemStream<T>`
      Parameters:
        `resource` - the output file

    - #### setMarshaller

          public void setMarshaller(org.springframework.oxm.Marshaller marshaller)

      Set Object to XML marshaller.
      Parameters:
        `marshaller` - the Object to XML marshaller

    - #### setHeaderCallback

          public void setHeaderCallback(StaxWriterCallback headerCallback)

      headerCallback is called before writing any items.
      Parameters:
        `headerCallback` - the `StaxWriterCallback` to be called prior to writing items.

    - #### setFooterCallback

          public void setFooterCallback(StaxWriterCallback footerCallback)

      footerCallback is called after writing all items but before closing the file.
      Parameters:
        `footerCallback` - the `StaxWriterCallback` to be called after writing items.

    - #### setTransactional

          public void setTransactional(boolean transactional)

      Flag to indicate that writes should be deferred to the end of a transaction if present. Defaults to true.
      Parameters:
        `transactional` - the flag to set

    - #### setForceSync

          public void setForceSync(boolean forceSync)

      Flag to indicate that changes should be force-synced to disk on flush. Defaults to false, which means that even with a local disk changes could be lost if the OS crashes in between a write and a cache flush. Setting to true may result in slower performance for usage patterns involving many frequent writes.
      Parameters:
        `forceSync` - the flag value to set

    - #### setShouldDeleteIfEmpty

          public void setShouldDeleteIfEmpty(boolean shouldDeleteIfEmpty)

      Flag to indicate that the target file should be deleted if no items have been written (other than header and footer) on close. Defaults to false.
      Parameters:
        `shouldDeleteIfEmpty` - the flag value to set

    - #### getEncoding

          public java.lang.String getEncoding()

      Get used encoding.
      Returns:
        the encoding used

    - #### setEncoding

          public void setEncoding(java.lang.String encoding)

      Set encoding to be used for output file.
      Parameters:
        `encoding` - the encoding to be used

    - #### getVersion

          public java.lang.String getVersion()

      Get XML version.
      Returns:
        the XML version used

    - #### setVersion

          public void setVersion(java.lang.String version)

      Set XML version to be used for output XML.
      Parameters:
        `version` - the XML version to be used

    - #### getStandalone

          public java.lang.Boolean getStandalone()

      Get used standalone document declaration.
      Returns:
        the standalone document declaration used
      Since:
        4.3

    - #### setStandalone

          public void setStandalone(java.lang.Boolean standalone)

      Set standalone document declaration to be used for output XML. If not set, standalone document declaration will be omitted.
      Parameters:
        `standalone` - the XML standalone document declaration to be used
      Since:
        4.3

    - #### getRootTagName

          public java.lang.String getRootTagName()

      Get the tag name of the root element.
      Returns:
        the root element tag name

    - #### setRootTagName

          public void setRootTagName(java.lang.String rootTagName)

      Set the tag name of the root element. If not set, default name is used ("root"). Namespace URI and prefix can also be set optionally using the notation:

           {uri}prefix:root

      The prefix is optional (defaults to empty), but if it is specified then the uri must be provided. In addition you might want to declare other namespaces using the `root attributes`.
      Parameters:
        `rootTagName` - the tag name to be used for the root element

    - #### getRootTagNamespacePrefix

          public java.lang.String getRootTagNamespacePrefix()

      Get the namespace prefix of the root element. Empty by default.
      Returns:
        the rootTagNamespacePrefix

    - #### getRootTagNamespace

          public java.lang.String getRootTagNamespace()

      Get the namespace of the root element.
      Returns:
        the rootTagNamespace

    - #### getRootElementAttributes

          public java.util.Map<java.lang.String,java.lang.String> getRootElementAttributes()

      Get attributes of the root element.
      Returns:
        attributes of the root element

    - #### setRootElementAttributes

          public void setRootElementAttributes(java.util.Map<java.lang.String,java.lang.String> rootElementAttributes)

      Set the root element attributes to be written. If any of the key names begin with "xmlns:" then they are treated as namespace declarations.
      Parameters:
        `rootElementAttributes` - attributes of the root element

    - #### setOverwriteOutput

          public void setOverwriteOutput(boolean overwriteOutput)

      Set "overwrite" flag for the output file. Flag is ignored when output file processing is restarted.
      Parameters:
        `overwriteOutput` - If set to true, output file will be overwritten (this flag is ignored when processing is restart).

    - #### setSaveState

          public void setSaveState(boolean saveState)

    - #### afterPropertiesSet

          public void afterPropertiesSet()
                                  throws java.lang.Exception

      Specified by:
        `afterPropertiesSet` in interface `org.springframework.beans.factory.InitializingBean`
      Throws:
        `java.lang.Exception` - thrown if error occurs
      See Also:
        `InitializingBean.afterPropertiesSet()`

    - #### open

          public void open(ExecutionContext executionContext)

      Open the output source
      Specified by:
        `open` in interface `ItemStream`
      Overrides:
        `open` in class `ItemStreamSupport`
      Parameters:
        `executionContext` - the batch context.
      See Also:
        `ItemStream.open(ExecutionContext)`

    - #### createXmlEventWriter

          protected javax.xml.stream.XMLEventWriter createXmlEventWriter(javax.xml.stream.XMLOutputFactory outputFactory,
                                                                         java.io.Writer writer)
                                                                  throws javax.xml.stream.XMLStreamException

      Subclasses can override to customize the writer.
      Parameters:
        `outputFactory` - the factory to be used to create an `XMLEventWriter`.
        `writer` - the `Writer` to be used by the `XMLEventWriter` for writing to character streams.
      Returns:
        an xml writer
      Throws:
        `javax.xml.stream.XMLStreamException` - thrown if error occured creating `XMLEventWriter`.

    - #### createXmlOutputFactory

          protected javax.xml.stream.XMLOutputFactory createXmlOutputFactory()
                                                                      throws javax.xml.stream.FactoryConfigurationError

      Subclasses can override to customize the factory.
      Returns:
        a factory for the xml output
      Throws:
        `javax.xml.stream.FactoryConfigurationError` - throw if an instance of this factory cannot be loaded.

    - #### createXmlEventFactory

          protected javax.xml.stream.XMLEventFactory createXmlEventFactory()
                                                                    throws javax.xml.stream.FactoryConfigurationError

      Subclasses can override to customize the event factory.
      Returns:
        a factory for the xml events
      Throws:
        `javax.xml.stream.FactoryConfigurationError` - thrown if an instance of this factory cannot be loaded.

    - #### createStaxResult

          protected javax.xml.transform.Result createStaxResult()

      Subclasses can override to customize the STAX result.
      Returns:
        a result for writing to

    - #### initNamespaceContext

          protected void initNamespaceContext(javax.xml.stream.XMLEventWriter writer)
                                       throws javax.xml.stream.XMLStreamException

      Inits the namespace context of the XMLEventWriter:
      - rootTagNamespacePrefix for rootTagName
      - any other xmlns namespace prefix declarations in the root element attributes
      Parameters:
        `writer` - XML event writer
      Throws:
        `javax.xml.stream.XMLStreamException` - thrown if error occurs while setting the prefix or default name space.

    - #### startDocument

          protected void startDocument(javax.xml.stream.XMLEventWriter writer)
                                throws javax.xml.stream.XMLStreamException

      Writes simple XML header containing:
      - xml declaration - defines encoding and XML version
      - opening tag of the root element and its attributes
      If this is not sufficient for you, simply override this method. Encoding, version and root tag name can be retrieved with corresponding getters.
      Parameters:
        `writer` - XML event writer
      Throws:
        `javax.xml.stream.XMLStreamException` - thrown if error occurs.

    - #### endDocument

          protected void endDocument(javax.xml.stream.XMLEventWriter writer)
                              throws javax.xml.stream.XMLStreamException

      Writes the EndDocument tag manually.
      Parameters:
        `writer` - XML event writer
      Throws:
        `javax.xml.stream.XMLStreamException` - thrown if error occurs.

    - #### close

          public void close()

      Flush and close the output source.
      Specified by:
        `close` in interface `ItemStream`
      Overrides:
        `close` in class `ItemStreamSupport`
      See Also:
        `ItemStream.close()`

    - #### write

          public void write(java.util.List<? extends T> items)
                     throws org.springframework.oxm.XmlMappingException,
                            java.io.IOException

      Write the value objects and flush them to the file.
      Specified by:
        `write` in interface `ItemWriter<T>`
      Parameters:
        `items` - the value object
      Throws:
        `java.io.IOException` - thrown if general error occurs.
        `org.springframework.oxm.XmlMappingException` - thrown if error occurs during XML Mapping.

    - #### update

          public void update(ExecutionContext executionContext)

      Get the restart data.
      Specified by:
        `update` in interface `ItemStream`
      Overrides:
        `update` in class `ItemStreamSupport`
      Parameters:
        `executionContext` - the batch context.
      See Also:
        `ItemStream.update(ExecutionContext)`