org.beanio
Interface BeanReader

All Known Implementing Classes:

BeanReaderImpl

public interface BeanReader

Interface for unmarshalling bean objects from an input stream.

A BeanReader is created using a StreamFactory and a mapping file.

Since:

1.0

Author:

Kevin Seim

See Also:

StreamFactory

Method Summary

void	close() Closes the underlying input stream.
int	getLineNumber() Returns the starting line number of the first record for the most recent bean object read from this reader, or -1 when the end of the stream is reached.
RecordContext	getRecordContext(int index) Returns record information for the most recent bean object read from this reader.
int	getRecordCount() Returns the number of records read from the underlying input stream for the most recent bean object read from this reader.
String	getRecordName() Returns the record or group name of the most recent bean object read from this reader, or null if the end of the stream was reached.
Object	read() Reads a single bean from the input stream.
void	setErrorHandler(BeanReaderErrorHandler errorHandler) Sets the error handler to handle exceptions thrown by read().
int	skip(int count) Skips ahead in the input stream.

Method Detail

read

Object read()
            throws BeanReaderIOException,
                   MalformedRecordException,
                   UnidentifiedRecordException,
                   UnexpectedRecordException,
                   InvalidRecordException

Reads a single bean from the input stream. If the end of the stream is reached, null is returned.

Returns:

the Java bean read, or null if the end of the stream was reached

Throws:

BeanReaderIOException - if the underlying input stream throws an IOException or this reader was closed

MalformedRecordException - if the underlying input stream is malformed and the record could not be accurately read

UnidentifiedRecordException - if the record type could not be identified

UnexpectedRecordException - if the record type is out of sequence

InvalidRecordException - if the record was identified and failed record or field level validations (including field type conversion errors)

skip

int skip(int count)
         throws BeanReaderIOException,
                MalformedRecordException,
                UnidentifiedRecordException,
                UnexpectedRecordException

Skips ahead in the input stream. Record validation errors are ignored, but a malformed record, unidentified record, or record out of sequence, will cause an exception that halts stream reading. Exceptions thrown by this method are not passed to the error handler.

Parameters:

count - the number of bean objects to skip over that would have been returned by calling read()

Returns:

the number of skipped bean objects, which may be less than count if the end of the stream was reached

Throws:

BeanReaderIOException - if the underlying input stream throws an IOException or this reader was closed

MalformedRecordException - if the underlying input stream is malformed and a record could not be accurately skipped

UnidentifiedRecordException - if a record could not be identified

UnexpectedRecordException - if a record is out of sequence

Since:

1.2

getRecordName

String getRecordName()

Returns the record or group name of the most recent bean object read from this reader, or null if the end of the stream was reached.

Returns:

the record or group name

getLineNumber

int getLineNumber()

Returns the starting line number of the first record for the most recent bean object read from this reader, or -1 when the end of the stream is reached. The line number may be zero if new lines are not used to separate characters.

Returns:

the line number

getRecordCount

int getRecordCount()

Returns the number of records read from the underlying input stream for the most recent bean object read from this reader. This typically returns 1 unless a bean object was mapped to a record group which may span multiple records.

Returns:

the record count

Since:

2.0

getRecordContext

RecordContext getRecordContext(int index)
                               throws IndexOutOfBoundsException

Returns record information for the most recent bean object read from this reader. If a bean object can span multiple records, getRecordCount() can be used to determine how many records were read from the stream.

Parameters:

index - the index of the record, starting at 0

Returns:

the RecordContext

Throws:

IndexOutOfBoundsException - if there is no record for the given index

Since:

2.0

See Also:

getRecordCount()

close

void close()
           throws BeanReaderIOException

Closes the underlying input stream.

Throws:

BeanReaderIOException - if the underlying input stream throws an IOException or this reader was already closed

setErrorHandler

void setErrorHandler(BeanReaderErrorHandler errorHandler)

Sets the error handler to handle exceptions thrown by read().

Parameters:

errorHandler - the BeanReaderErrorHandler