com.ricebridge.xmlman
Interface BadRecordListener

All Known Implementing Classes:

BadRecordListenerSupport

public interface BadRecordListener

Implement this interface by extending BadRecordListenerSupport to receive a BadRecord object for each failed data record.

This callback interface allows you to handle failed data records as soon as they occur. The most common use-case is to log them for debugging purposes.

Once you have created your own BadRecordListener, you can use it by calling the setBadRecordListener method of XmlManager before starting the the load or save process (BadRecordListener receives failed data records from both load and save processes).

The getBadRecords method of XmlManager is implemented by using the StandardBadRecordListener class, which you should review if you are going to write your own BadRecordListener.

When using your own BadRecordListener you should probably set the setIgnoreBadRecords setting to true, so that you receive all the failed data records.

Calling Sequence
When used with a RecordListener or a RecordProvider, the following method calling sequence is followed:

1. RecordListener.startProcess OR RecordProvider.startProcess
2. BadRecordListener.startProcess
3. RecordListener.handleRecord OR RecordProvider.hasNextRecord, RecordProvider.nextRecord
4. BadRecordListener.handleBadRecord
5. BadRecordListener.endProcess
6. RecordListener.endProcess OR RecordProvider.endProcess

Important
In order to ensure the greatest compatibility with future releases and to take advantage of additional error handling functionality, please implement your RecordListener by extending the abstract BadRecordListenerSupport class. This class ensures that all data you receive is well-formed (no nulls), and also creates standard exceptions when problems do occur.

In fact, you should probably extend the abstract CollectingBadRecordListener class, to ensure that the getBadRecords method continues to function correctly.

The Source Code of this Java class is available under a BSD-style license.

Method Summary

void	endProcess() Indicate the end of the loading or saving process.
void	handleBadRecord(BadRecord pBadRecord) Handle a failed data record.
void	startProcess() Indicate the start of the loading or saving process.

Method Detail

startProcess

public void startProcess()

Indicate the start of the loading or saving process.

This method is called after the RecordListener.startProcess() and RecordProvider.startProcess() methods. You can initialise any logging facilities or other resources that you need to use to process the failed data records.

handleBadRecord

public void handleBadRecord(BadRecord pBadRecord)

Handle a failed data record.

As soon as XML Manager detects a failed data record, this method is called so that you can log the problem,or deal with it in another manner.

Parameters:

pBadRecord - BadRecord object describing the error

endProcess

public void endProcess()

Indicate the end of the loading or saving process.

This method is called before the RecordListener.endProcess() and RecordProvider.endProcess() methods. You can use it to release any resources that you were using to handle the failed data records.

Note: this method will be called even if other errors occur, so long as the call to startProcess() returned normally. If your startProcess method does critical things, make sure that it fails cleanly.