Package 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
  Description
  `static final String`
  `DEFAULT_ENCODING`
  `static final String`
  `DEFAULT_ROOT_TAG_NAME`
  `static final Boolean`
  `DEFAULT_STANDALONE_DOCUMENT`
  `static final String`
  `DEFAULT_XML_VERSION`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `StaxEventItemWriter()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `afterPropertiesSet()`
  `void`
  `close()`
  Flush and close the output source.
  `protected Result`
  `createStaxResult()`
  Subclasses can override to customize the STAX result.
  `protected XMLEventFactory`
  `createXmlEventFactory()`
  Subclasses can override to customize the event factory.
  `protected XMLEventWriter`
  `createXmlEventWriter(XMLOutputFactory outputFactory, Writer writer)`
  Subclasses can override to customize the writer.
  `protected XMLOutputFactory`
  `createXmlOutputFactory()`
  Subclasses can override to customize the factory.
  `protected void`
  `endDocument(XMLEventWriter writer)`
  Writes the EndDocument tag manually.
  `String`
  `getEncoding()`
  Get used encoding.
  `Map<String,String>`
  `getRootElementAttributes()`
  Get attributes of the root element.
  `String`
  `getRootTagName()`
  Get the tag name of the root element.
  `String`
  `getRootTagNamespace()`
  Get the namespace of the root element.
  `String`
  `getRootTagNamespacePrefix()`
  Get the namespace prefix of the root element.
  `Boolean`
  `getStandalone()`
  Get used standalone document declaration.
  `String`
  `getVersion()`
  Get XML version.
  `protected void`
  `initNamespaceContext(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(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(Map<String,String> rootElementAttributes)`
  Set the root element attributes to be written.
  `void`
  `setRootTagName(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(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(String version)`
  Set XML version to be used for output XML.
  `protected void`
  `startDocument(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(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 Details

  - ### DEFAULT_ENCODING

    public static final String DEFAULT_ENCODING
    See Also:
      - Constant Field Values

  - ### DEFAULT_XML_VERSION

    public static final String DEFAULT_XML_VERSION
    See Also:
      - Constant Field Values

  - ### DEFAULT_STANDALONE_DOCUMENT

    public static final Boolean DEFAULT_STANDALONE_DOCUMENT

  - ### DEFAULT_ROOT_TAG_NAME

    public static final String DEFAULT_ROOT_TAG_NAME
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### StaxEventItemWriter

    public StaxEventItemWriter()

- ## Method Details

  - ### 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 String getEncoding()
    Get used encoding.
    Returns:
      the encoding used

  - ### setEncoding

    public void setEncoding(String encoding)
    Set encoding to be used for output file.
    Parameters:
      `encoding` - the encoding to be used

  - ### getVersion

    public String getVersion()
    Get XML version.
    Returns:
      the XML version used

  - ### setVersion

    public void setVersion(String version)
    Set XML version to be used for output XML.
    Parameters:
      `version` - the XML version to be used

  - ### getStandalone

    public Boolean getStandalone()
    Get used standalone document declaration.
    Returns:
      the standalone document declaration used
    Since:
      4.3

  - ### setStandalone

    public void setStandalone(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 String getRootTagName()
    Get the tag name of the root element.
    Returns:
      the root element tag name

  - ### setRootTagName

    public void setRootTagName(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 String getRootTagNamespacePrefix()
    Get the namespace prefix of the root element. Empty by default.
    Returns:
      the rootTagNamespacePrefix

  - ### getRootTagNamespace

    public String getRootTagNamespace()
    Get the namespace of the root element.
    Returns:
      the rootTagNamespace

  - ### getRootElementAttributes

    public Map<String,String> getRootElementAttributes()
    Get attributes of the root element.
    Returns:
      attributes of the root element

  - ### setRootElementAttributes

    public void setRootElementAttributes(Map<String,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 Exception
    Specified by:
      `afterPropertiesSet` in interface `org.springframework.beans.factory.InitializingBean`
    Throws:
      `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 XMLEventWriter createXmlEventWriter(XMLOutputFactory outputFactory, Writer writer) throws 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:
      `XMLStreamException` - thrown if error occured creating `XMLEventWriter`.

  - ### createXmlOutputFactory

    protected XMLOutputFactory createXmlOutputFactory() throws FactoryConfigurationError
    Subclasses can override to customize the factory.
    Returns:
      a factory for the xml output
    Throws:
      `FactoryConfigurationError` - throw if an instance of this factory cannot be loaded.

  - ### createXmlEventFactory

    protected XMLEventFactory createXmlEventFactory() throws FactoryConfigurationError
    Subclasses can override to customize the event factory.
    Returns:
      a factory for the xml events
    Throws:
      `FactoryConfigurationError` - thrown if an instance of this factory cannot be loaded.

  - ### createStaxResult

    protected Result createStaxResult()
    Subclasses can override to customize the STAX result.
    Returns:
      a result for writing to

  - ### initNamespaceContext

    protected void initNamespaceContext(XMLEventWriter writer) throws 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:
      `XMLStreamException` - thrown if error occurs while setting the prefix or default name space.

  - ### startDocument

    protected void startDocument(XMLEventWriter writer) throws 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:
      `XMLStreamException` - thrown if error occurs.

  - ### endDocument

    protected void endDocument(XMLEventWriter writer) throws XMLStreamException
    Writes the EndDocument tag manually.
    Parameters:
      `writer` - XML event writer
    Throws:
      `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(List<? extends T> items) throws org.springframework.oxm.XmlMappingException, IOException
    Write the value objects and flush them to the file.
    Specified by:
      `write` in interface `ItemWriter<T>`
    Parameters:
      `items` - the value object
    Throws:
      `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)`