Package 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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_ENCODING`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `StaxEventItemReader()`

- ## Method Summary

  Modifier and Type
  Method
  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 boolean`
  `isFragmentRootElementName(QName name)`
  `protected void`
  `jumpToItem(int itemIndex)`
  Move to the given item index.
  `protected boolean`
  `moveCursorToNextFragment(XMLEventReader reader)`
  Responsible for moving the cursor before the StartElement of the fragment root.
  `void`
  `setEncoding(String encoding)`
  Set encoding to be used for the input file.
  `void`
  `setFragmentRootElementName(String fragmentRootElementName)`
  `void`
  `setFragmentRootElementNames(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(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.ItemReader

  `read`

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

  `close, open, update`

- ## Field Details

  - ### DEFAULT_ENCODING

    public static final String DEFAULT_ENCODING

- ## Constructor Details

  - ### StaxEventItemReader

    public StaxEventItemReader()

- ## Method Details

  - ### 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(String fragmentRootElementName)
    Parameters:
      `fragmentRootElementName` - name of the root element of the fragment

  - ### setFragmentRootElementNames

    public void setFragmentRootElementNames(String[] fragmentRootElementNames)
    Parameters:
      `fragmentRootElementNames` - list of the names of the root element of the fragment

  - ### setXmlInputFactory

    public void setXmlInputFactory(XMLInputFactory xmlInputFactory)
    Set the `XMLInputFactory`.
    Parameters:
      `xmlInputFactory` - to use

  - ### setEncoding

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

  - ### afterPropertiesSet

    public void afterPropertiesSet() throws 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:
      `IllegalArgumentException` - if the Resource, FragmentDeserializer or FragmentRootElementName is null, or if the root element is empty.
      `IllegalStateException` - if the Resource does not exist.
      `Exception`
    See Also:
      - `InitializingBean.afterPropertiesSet()`

  - ### moveCursorToNextFragment

    protected boolean moveCursorToNextFragment(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 Exception
    Description copied from class: `AbstractItemCountingItemStreamItemReader`
    Close the resources opened in `AbstractItemCountingItemStreamItemReader.doOpen()`.
    Specified by:
      `doClose` in class `AbstractItemCountingItemStreamItemReader<T>`
    Throws:
      `Exception` - Allows subclasses to throw checked exceptions for interpretation by the framework

  - ### doOpen

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

  - ### doRead

    @Nullable protected T doRead() throws IOException, 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:
      `IOException`
      `XMLStreamException`

  - ### jumpToItem

    protected void jumpToItem(int itemIndex) throws 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:
      `Exception` - Allows subclasses to throw checked exceptions for interpretation by the framework

  - ### isFragmentRootElementName

    protected boolean isFragmentRootElementName(QName name)