com.ricebridge.xmlman
Interface RecordProvider

All Known Implementing Classes:

RecordProviderSupport

public interface RecordProvider

Implement this interface by extending RecordProviderSupport to provide each data record for saving.

This callback interface allows you to provide data records on demand so that they can be saved as quickly as possible with minimal memory usage. This means that you can avoid storing all the data you want to save in memory at the same time. For example, if you want to save data from a database to an XML file, you do not have to load all the data at once, but can step through the ResultSet and save each record directly. See the database example for more information.

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

1. setXmlSpec
2. setFieldNames
3. startProcess
4. hasNextRecord
5. nextRecord
6. endProcess

The hasNextRecord and nextRecord methods are called called in sequence, once for each data record.

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

Error Handling
If an error occurs when you are creating the data for the next record, you can 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 save 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 RecordProvider by extending the abstract RecordProviderSupport class. This class 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 saving process.
boolean	hasNextRecord() Indicate that another data record is available to save.
String[]	nextRecord() Provide each data record as a String[] array for the XML target 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 saving 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, TableModelRecordProvider uses the custom property TableModel.saveHeaders to output the headers of the TableModel that it is saving as the first data record. 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 BeanRecordProvider class uses the field names to determine the correct get methods to call.

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

When you extend RecordProviderSupport to implement the RecordProvider 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 RecordProviderSupport.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 saving process.

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

hasNextRecord

public boolean hasNextRecord()

Indicate that another data record is available to save.

Each data record is converted into XML by first calling this method to check that another data record is available, and then calling nextRecord() to get the actual data. Once this method returns false, processing finishes.

nextRecord

public String[] nextRecord()

Provide each data record as a String[] array for the XML target document.

This is the most important method of the RecordProvider interface. This is where you actually provide your data to XML Manager. The data is provided as a String[] array of field values. You should always return a String[] array that is equal in length to the number of field paths specified in the RecordSpec. Any null fields are set to empty strings, and any missing fields are also set to empty strings. Any additional elements are ignored.

endProcess

public void endProcess()

Indicate the end of the saving process.

This method is called once the XML source document has been fully output. You can use it to release any resources such as database connections that you were using to create 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.