org.springframework.batch.item
Interface ItemReader

All Known Subinterfaces:

LineReader

All Known Implementing Classes:

AbstractItemReader, AbstractItemStreamItemReader, AggregateItemReader, DelegatingItemReader, DrivingQueryItemReader, FlatFileItemReader, HibernateCursorItemReader, IbatisDrivingQueryItemReader, ItemReaderAdapter, JdbcCursorItemReader, JmsItemReader, ListItemReader, ResourceLineReader, StaxEventItemReader, ValidatingItemReader

public interface ItemReader

Strategy interface for providing the data.
Implementations are expected to be stateful and will be called multiple times for each batch, with each call to read() returning a different value and finally returning null when all input data is exhausted.
Implementations need to be thread safe and clients of a ItemReader need to be aware that this is the case.
A richer interface (e.g. with a look ahead or peek) is not feasible because we need to support transactions in an asynchronous batch.

Since:

1.0

Author:

Rob Harrop, Dave Syer, Lucas Ward

Method Summary

void	mark() Mark the stream so that it can be reset later and the items backed out. Mark is called before reading a new chunk of items - in case of rollback mark will not be called again before re-processing the chunk. In a multi-threaded setting implementations have to ensure that only the state from the current thread is saved.
Object	read() Reads a piece of input data and advance to the next one.
void	reset() Reset the stream to the last mark.

Method Detail

read

Object read()
            throws Exception,
                   UnexpectedInputException,
                   NoWorkFoundException,
                   ParseException

Reads a piece of input data and advance to the next one. Implementations must return null at the end of the input data set. In a transactional setting, caller might get the same item twice from successive calls (or otherwise), if the first call was in a transaction that rolled back.

Throws:

Exception - if an underlying resource is unavailable.

UnexpectedInputException

NoWorkFoundException

ParseException

mark

void mark()
          throws MarkFailedException

Mark the stream so that it can be reset later and the items backed out.
Mark is called before reading a new chunk of items - in case of rollback mark will not be called again before re-processing the chunk.
In a multi-threaded setting implementations have to ensure that only the state from the current thread is saved.

Throws:

MarkFailedException - if there is a problem with the mark. If a mark fails inside a transaction, it would be worrying, but not normally fatal.

reset

void reset()
           throws ResetFailedException

Reset the stream to the last mark. After a reset the stream state will be such that changes (items read or written) since the last call to mark will not be visible after a call to close.
In a multi-threaded setting implementations have to ensure that only the state from the current thread is reset.

Throws:

ResetFailedException - if there is a problem with the reset. If a reset fails inside a transaction, it would normally be fatal, and would leave the stream in an inconsistent state. So while this is an unchecked exception, it may be important for a client to catch it explicitly.