org.springframework.batch.item.xml

## Class StaxEventItemReader<T>

- java.lang.Object
- - org.springframework.batch.item.ItemStreamSupport
  - - org.springframework.batch.item.support.AbstractItemStreamItemReader<T>
    - - org.springframework.batch.item.support.AbstractItemCountingItemStreamItemReader<T>
      - - org.springframework.batch.item.xml.StaxEventItemReader<T>

- All Implemented Interfaces:
    ResourceAwareItemReaderItemStream<T>, ItemReader<T>, ItemStream, ItemStreamReader<T>, org.springframework.beans.factory.InitializingBean

      public class StaxEventItemReader<T>
      extends AbstractItemCountingItemStreamItemReader<T>
      implements ResourceAwareItemReaderItemStream<T>, org.springframework.beans.factory.InitializingBean

  Item reader for reading XML input based on StAX. It extracts fragments from the input XML document which correspond to records for processing. The fragments are wrapped with StartDocument and EndDocument events so that the fragments can be further processed like standalone XML documents. The implementation is not thread-safe.
  Author:
    Robert Kasanicky, Mahmoud Ben Hassine

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `StaxEventItemReader()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Ensure that all required dependencies for the ItemReader to run are provided after all properties have been set.
    `protected void` | `doClose()` Close the resources opened in `AbstractItemCountingItemStreamItemReader.doOpen()`.
    `protected void` | `doOpen()` Open resources necessary to start reading input.
    `protected T` | `doRead()` Move to next fragment and map it to item.
    `protected void` | `jumpToItem(int itemIndex)` Move to the given item index.
    `protected boolean` | `moveCursorToNextFragment(javax.xml.stream.XMLEventReader reader)` Responsible for moving the cursor before the StartElement of the fragment root.
    `void` | `setFragmentRootElementName(java.lang.String fragmentRootElementName)`
    `void` | `setFragmentRootElementNames(java.lang.String[] fragmentRootElementNames)`
    `void` | `setResource(org.springframework.core.io.Resource resource)`
    `void` | `setStrict(boolean strict)` In strict mode the reader will throw an exception on `AbstractItemCountingItemStreamItemReader.open(org.springframework.batch.item.ExecutionContext)` if the input resource does not exist.
    `void` | `setUnmarshaller(org.springframework.oxm.Unmarshaller unmarshaller)`
    `void` | `setXmlInputFactory(javax.xml.stream.XMLInputFactory xmlInputFactory)` Set the `XMLInputFactory`.

    - ### Methods inherited from class org.springframework.batch.item.support.AbstractItemCountingItemStreamItemReader

      `close, getCurrentItemCount, isSaveState, open, read, setCurrentItemCount, setMaxItemCount, setSaveState, update`

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

    - ### Methods inherited from interface org.springframework.batch.item.ItemStream

      `close, open, update`

    - ### Methods inherited from interface org.springframework.batch.item.ItemReader

      `read`

- - ### Constructor Detail

    - #### StaxEventItemReader

          public StaxEventItemReader()

  - ### Method Detail

    - #### setStrict

          public void setStrict(boolean strict)

      In strict mode the reader will throw an exception on `AbstractItemCountingItemStreamItemReader.open(org.springframework.batch.item.ExecutionContext)` if the input resource does not exist.
      Parameters:
        `strict` - true by default

    - #### setResource

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

      Specified by:
        `setResource` in interface `ResourceAwareItemReaderItemStream<T>`

    - #### setUnmarshaller

          public void setUnmarshaller(org.springframework.oxm.Unmarshaller unmarshaller)

      Parameters:
        `unmarshaller` - maps xml fragments corresponding to records to objects

    - #### setFragmentRootElementName

          public void setFragmentRootElementName(java.lang.String fragmentRootElementName)

      Parameters:
        `fragmentRootElementName` - name of the root element of the fragment

    - #### setFragmentRootElementNames

          public void setFragmentRootElementNames(java.lang.String[] fragmentRootElementNames)

      Parameters:
        `fragmentRootElementNames` - list of the names of the root element of the fragment

    - #### setXmlInputFactory

          public void setXmlInputFactory(javax.xml.stream.XMLInputFactory xmlInputFactory)

      Set the `XMLInputFactory`.
      Parameters:
        `xmlInputFactory` - to use

    - #### afterPropertiesSet

          public void afterPropertiesSet()
                                  throws java.lang.Exception

      Ensure that all required dependencies for the ItemReader to run are provided after all properties have been set.
      Specified by:
        `afterPropertiesSet` in interface `org.springframework.beans.factory.InitializingBean`
      Throws:
        `java.lang.IllegalArgumentException` - if the Resource, FragmentDeserializer or FragmentRootElementName is null, or if the root element is empty.
        `java.lang.IllegalStateException` - if the Resource does not exist.
        `java.lang.Exception`
      See Also:
        `InitializingBean.afterPropertiesSet()`

    - #### moveCursorToNextFragment

          protected boolean moveCursorToNextFragment(javax.xml.stream.XMLEventReader reader)
                                              throws NonTransientResourceException

      Responsible for moving the cursor before the StartElement of the fragment root. This implementation simply looks for the next corresponding element, it does not care about element nesting. You will need to override this method to correctly handle composite fragments.
      Parameters:
        `reader` - the `XMLEventReader` to be used to find next fragment.
      Returns:
        `true` if next fragment was found, `false` otherwise.
      Throws:
        `NonTransientResourceException` - if the cursor could not be moved. This will be treated as fatal and subsequent calls to read will return null.

    - #### doClose

          protected void doClose()
                          throws java.lang.Exception

      Description copied from class: `AbstractItemCountingItemStreamItemReader`
      Close the resources opened in `AbstractItemCountingItemStreamItemReader.doOpen()`.
      Specified by:
        `doClose` in class `AbstractItemCountingItemStreamItemReader<T>`
      Throws:
        `java.lang.Exception` - Allows subclasses to throw checked exceptions for interpretation by the framework

    - #### doOpen

          protected void doOpen()
                         throws java.lang.Exception

      Description copied from class: `AbstractItemCountingItemStreamItemReader`
      Open resources necessary to start reading input.
      Specified by:
        `doOpen` in class `AbstractItemCountingItemStreamItemReader<T>`
      Throws:
        `java.lang.Exception` - Allows subclasses to throw checked exceptions for interpretation by the framework

    - #### doRead

          @Nullable
          protected T doRead()
                                throws java.io.IOException,
                                       javax.xml.stream.XMLStreamException

      Move to next fragment and map it to item.
      Specified by:
        `doRead` in class `AbstractItemCountingItemStreamItemReader<T>`
      Returns:
        an item or `null` if the data source is exhausted
      Throws:
        `java.io.IOException`
        `javax.xml.stream.XMLStreamException`

    - #### jumpToItem

          protected void jumpToItem(int itemIndex)
                             throws java.lang.Exception

      Description copied from class: `AbstractItemCountingItemStreamItemReader`
      Move to the given item index. Subclasses should override this method if there is a more efficient way of moving to given index than re-reading the input using `AbstractItemCountingItemStreamItemReader.doRead()`.
      Overrides:
        `jumpToItem` in class `AbstractItemCountingItemStreamItemReader<T>`
      Parameters:
        `itemIndex` - index of item (0 based) to jump to.
      Throws:
        `java.lang.Exception` - Allows subclasses to throw checked exceptions for interpretation by the framework