com.ricebridge.xmlman
Interface RecordListener

All Known Implementing Classes:

RecordListenerSupport

public interface RecordListener

Implement this interface by extending RecordListenerSupport to receive each data record as it is loaded.

This callback interface allows you to handle data records as they are loaded. This is the fastest way to load data and also means that you can avoid storing all of the data in memory at once. The most common use-case is database loading, where individual XML data records are converted to SQL statements that are executed immediately. See the database example for more information.

Once you have created your own RecordListener, you can use it by calling the load methods of XmlManager that accept a RecordListener as an argument, for example: XmlManager.load(File,RecordSpec,RecordListener). XmlManager than starts to load the data and calls the methods of the RecordListener in a defined sequence:

1. setXmlSpec
2. setFieldNames
3. startProcess
4. handleRecord
5. endProcess

The handleRecord method is called once for each data record in the source XML.

When writing your own RecordListener, the easiest way to get started is to review the source code for the existing RecordListeners used by XmlManager. XmlManager uses RecordListeners internally for all data loading operations. The StringArrayRecordListener is a very simple example and a good place to start.

Error Handling
The handleRecord method can return a BadRecord object that describes any semantically incorrect data records. This allows you to perform validation against the input data. You can also return a BadRecord when database access fails, or some other problem occurs. When everything is OK, there is no need to return a BadRecord, simply return null from the handleRecord method. You can also allow Exceptions to pass up to the support class, without handling them yourself. In this case XmlManager will handle them for you, either halting the load operation, or creating a BadRecord and storing it, depending on the value of the XmlSpec.setIgnoreBadRecords(boolean) setting.

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 RecordListenerSupport class. This class ensures that all data you receive is well-formed (no nulls), and also creates standard exceptions when problems do occur.

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

Method Summary

void	endProcess() Indicate the end of the loading process.
BadRecord	handleRecord(String[] pRecord, long pRecordNumber) Handle each data record as it is parsed from the XML source document.
void	setFieldNames(String[] pFieldNames) Set the field names of the primary RecordSpec.
void	setXmlSpec(XmlSpec pXmlSpec) Set the current XmlSpec settings.
void	startProcess() Indicate the start of the loading process.

Method Detail

setXmlSpec

public void setXmlSpec(XmlSpec pXmlSpec)

Set the current XmlSpec settings.

You can implement this method to get the values of the current settings, and use them to modify your data handling. For example, TableModelRecordListener uses the custom property TableModel.editable to make any TableModels that it returns editable. You can easily use your own custom properties by calling the XmlSpec.setProperty method.

Parameters:

pXmlSpec - XmlSpec object

setFieldNames

public void setFieldNames(String[] pFieldNames)

Set the field names of the primary RecordSpec.

You can implement this method to get the list of field names that apply to the data. This is useful when you need to identify the data fields for additional functionality. For example, the BeanRecordListener class uses the field names to determine the correct set methods to call.

Note: if no field names are provided in the primary RecordSpec, then this method is not called.

When you extend RecordListenerSupport to implement the RecordListener interface, you gain access to the protected instance variable iFieldNames, which will contain any field names if provided, or otherwise be empty. You can override the RecordListenerSupport.setFieldNamesImpl(java.lang.String[]) method to handle the field names in a different manner.

If more than one RecordSpec was specified, then only the field names from the primary RecordSpec are used. See the RecordSpec documentation for details.

Parameters:

pFieldNames - String[] of field names

startProcess

public void startProcess()

Indicate the start of the loading process.

This method is called just before loading from the XML source document begins. You can initialise any database connections or other resources that you need to use to process the data.

handleRecord

public BadRecord handleRecord(String[] pRecord,
                              long pRecordNumber)

Handle each data record as it is parsed from the XML source document.

This is the most important method of the RecordListener interface. This is where you actually receive your data. The data is provided as a String[] array of field values. You will always get a String[] array that is equal in length to the number of field paths specified in the RecordSpec. Any empty fields are set to empty strings.

The pRecordNumber argument contains a count of the number of records parsed so far. It starts at 1, not 0. The count is separate for each RecordSpec, so if you are using multiple RecordSpecs, you will need to provide your own global counter that is shared between all the RecordListeners that you are using.

Parameters:

pRecord - record data as a String[]

pRecordNumber - current count of records

Returns:

BadRecord if there was a problem, null otherwise

endProcess

public void endProcess()

Indicate the end of the loading process.

This method is called once the XML source document has been fully parsed. You can use it to release any resources such as database connections that you were using to handle the data.

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.