com.ricebridge.csvman
Interface LineProvider

All Known Implementing Classes:

LineProviderSupport, LineProviderSupportImpl

public interface LineProvider

Use this interface to create custom CSV data savers.

This callback interface allows you to provide data lines 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 a CSV file, you do not have to load all the data at once. Instead you can step through the ResultSet and save each line directly. See the database example for more information.

To implement this interface, please extend CustomLineProvider, as that will help keep your code compatible with future versions. To use a LineProvider, call the CsvManager.save(Object, LineProvider) or CsvManager.save(Object, LineSpec, LineProvider) methods.

When you pass an instance of LineProvider to CsvManager, it will call the hasNextLine and nextLine methods to get each data line to save. You then provide the data line as a String[] array.

As CsvManager saves the data, it calls the methods of the LineProvider in a defined sequence:

1. setCsvSpec
2. setLineSpec
3. startProcess
4. hasNextLine
5. nextLine
6. endProcess

The hasNextLine and nextLine methods are called called repeatedly, once for each data line.

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

Here is the full list of standard LineProviders:

• BasicLineProvider
• AsListsLineProvider
• TableModelLineProvider
• ResultSetLineProvider
• BeanLineProvider

Note: you may assume in your implementation that no parameters are null.

Error Handling
If an error occurs when you are creating the data for the next line, you can allow Exceptions to pass up to the CustomLineProvider class, without handling them yourself. In this case CsvManager will handle them for you, either halting the save operation, or creating a BadLine and storing it, depending on the value of the CsvSpec.setIgnoreBadLines(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 LineProvider by extending the abstract CustomLineProvider class. This class ensures that all data you receive is well-formed (no nulls), and also creates standard exceptions when problems do occur.

Compatibility Note: CSV Manager 1.1 used LineProviderSupport instead of CustomLineProvider. Existing code will still work with this base class, but you should always use CustomLineProvider for new code.

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	hasNextLine() Indicate that another data line is available to save.
String[]	nextLine() Provide each data line as a String[] array for the CSV output.
void	setCsvSpec(CsvSpec pCsvSpec) Set the current CsvSpec settings.
void	setLineSpec(LineSpec pLineSpec) Set the current LineSpec field specification settings.
void	startProcess() Called just before saving of the CSV data starts.

Method Detail

setCsvSpec

public void setCsvSpec(CsvSpec pCsvSpec)

Set the current CsvSpec settings.

You can implement this method to get the values of the current settings, and use them to modify your data handling. For example, TableModelLineProvider uses the custom property TableModel.saveHeaders to output the headers of the TableModel that it is saving as the first data line. You can easily use your own custom properties by calling the CsvSpec.setProperty and CsvSpec.getProperty methods.

Note: to actually set the CsvSpec object, you use CsvManager.setCsvSpec.

Implement by overriding CustomLineProvider.setCsvSpecImpl.

Parameters:

pCsvSpec - CsvSpec object

setLineSpec

public void setLineSpec(LineSpec pLineSpec)

Set the current LineSpec field specification settings.

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 BeanLineProvider class uses the field names to determine the correct get methods to call.

You can add your own metadata for use by CustomLineProviders by subclassing LineSpec and adding appropriate methods to return your custom metadata.

Implement by overriding CustomLineProvider.setLineSpecImpl.

Parameters:

pLineSpec - field specification

startProcess

public void startProcess()

Called just before saving of the CSV data starts.

You should use this method to initialise any data sources in your LineProvider. For example, you can initialise any database connections or other resources that you need to use to process the data.

Implement by overriding CustomLineProvider.startProcessImpl.

hasNextLine

public boolean hasNextLine()

Indicate that another data line is available to save.

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

You use this method to control the saving process. Keep returning true as long as you have more data lines to save.

Implement by overriding CustomLineProvider.hasNextLineImpl.

nextLine

public String[] nextLine()

Provide each data line as a String[] array for the CSV output.

This is the most important method of the LineProvider interface. This is where you actually provide your data to CSV Manager. The data is provided as a String[] array of field values. Any null fields are set to empty strings, and any missing fields are also set to empty strings (when using CsvSpec.setNumFields.

Implement by overriding CustomLineProvider.nextLineImpl.

endProcess

public void endProcess()

Indicate the end of the saving process.

This method is called once the CSV output has been fully completed. You can use it to release any resources such as database connections that you were using to create the data.

Implement by overriding CustomLineProvider.endProcessImpl.