com.ricebridge.csvman
Interface LineListener

All Known Implementing Classes:

LineListenerSupport, LineListenerSupportImpl

public interface LineListener

Use this interface to create custom CSV data loaders.

This callback interface allows you to handle each data line separately as it is loaded. To implement this interface, please extend CustomLineListener, as that will help keep your code compatible with future versions.

To use a LineListener, call the CsvManager.load(Object, LineListener) or CsvManager.load(Object, LineSpec, LineListener) methods.

When you pass an instance of LineListener to CsvManager, it will call the handleLine method each time a data line is loaded. The string values of the data fields are provided as a String[] array. When a badly formatted line is encountered, the handleBadLine method is called instead.

As CsvManager loads the CSV data, it calls the methods of the LineListener in a defined sequence:

1. setCsvSpec
2. setLineSpec
3. startProcess
4. handleLine
5. endProcess

The handleLine method is called once for each line in the CSV file.

When writing your own LineListener, the easiest way to get started is to review the source code for the existing LineListeners used by CsvManager. CsvManager uses LineListeners internally for all data loading operations. The BasicLineListener is a very simple example and a good place to start. Here is the full list of standard LineListeners:

• BasicLineListener
• AsListsLineListener
• TableModelLineListener
• ResultSetLineListener
• BeanLineListener

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

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

If you set setIgnoreBadLines to true then loading of CSV data will continue even when badly formatted data lines are encountered. If this setting is false (the default), then loading is halted and a CsvManagerException (CODE_bad_line) is thrown after handleBadLine is called.

Important
In order to ensure the greatest compatibility with future releases and to take advantage of additional error handling functionality, please implement your LineListener by extending the abstract CustomLineListener 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 LineListenerSupport instead of CustomLineListener. Existing code will still work with this base class, but you should always use CustomLineListener for new code.

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

See Also:

CustomLineListener, BasicLineListener, CsvManager, CsvManagerException

Method Summary

void	endProcess() Called just after loading of the CSV data ends.
void	handleBadLine(BadLine pBadLine) Called when a badly formatted data line is encountered.
BadLine	handleLine(String[] pLine, int pNumFields, long pLineNumber, String pOriginalLine) Implement this method to directly access the data for each line as it is parsed.
void	setCsvSpec(CsvSpec pCsvSpec) Set the current CsvSpec settings.
void	setLineSpec(LineSpec pLineSpec) Set the current LineSpec settings.
void	startProcess() Called just before loading 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, TableModelLineListener 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 CsvSpec.setProperty method.

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

Implement by overriding CustomLineListener.setCsvSpecImpl.

Parameters:

pCsvSpec - CsvSpec object

setLineSpec

public void setLineSpec(LineSpec pLineSpec)

Set the current LineSpec settings.

You can implement this method to get the current LineSpec you specified for the data you are loading. The LineSpec provides additional information about each data field. For example, BeanLineListener uses the field names metadata to determine the right get and set methods for each data field.

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

Implement by overriding CustomLineListener.setLineSpecImpl.

Parameters:

pLineSpec - LineSpec object

startProcess

public void startProcess()

Called just before loading of the CSV data starts.

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

Implement by overriding CustomLineListener.startProcessImpl.

See Also:

endProcess()

handleLine

public BadLine handleLine(String[] pLine,
                          int pNumFields,
                          long pLineNumber,
                          String pOriginalLine)

Implement this method to directly access the data for each line as it is parsed.

The parameter pLine is a String[] that is normally setNumFields in length. If fewer than pNumFields columns are found in the current line, then the remaining elements of pLine are empty strings. If more than pNumFields columns are found, then pLine is a String[] array large enough to contain all data fields found. In both cases, the parameter pNumFields indicates the exact number of data fields found.

This method should return a BadLine object if the data in pLine was invalid in some way. Data lines that cannot be parsed due to syntax errors are not sent to the LineListener via this method. However, syntactically correct lines may still contain invalid data and this should be indicated by returning a BadLine object describing the problem from this method. Return null if the data was acceptable. This return value is used to maintain internal bad line counts so that the loading statistics are correct. The use of a return value rather than an Exception was chosen for performance reasons. You may still throw a RuntimeException from within this method and CsvManager will record the error, passing on the Exception contained in a CsvManagerException (CODE_internal_exception, or continuing to load data if CsvManager.setIgnoreBadLines(boolean) is true.

Implement by overriding CustomLineListener.handleLineImpl.

Parameters:

pLine - line data as text

pNumFields - number of data fields found

pLineNumber - line number index, counting from 1

pOriginalLine - original line of data

Returns:

null if line is OK, BadLine object if line was bad in some way

handleBadLine

public void handleBadLine(BadLine pBadLine)

Called when a badly formatted data line is encountered.

This method is only called once (and data loading stops) if CsvManager.setIgnoreBadLines(boolean) is false (the default). If CsvManager.setIgnoreBadLines(boolean) is true, each badly formatted line is sent to the LineListener implementation via this method.

The text of the badly formatted line is given by BadLine.getOriginalLine() and the parser error message (or other internal error) is given in the BadLine.getErrorMsg().

The error message description passed to this method is not suitable for non-technical users. To get a user-friendly message set CsvManager.setIgnoreBadLines(boolean) to false and call CsvManagerException.toString() on any CsvManagerExceptions that are thrown while loading CSV data.

Implement by overriding CustomLineListener.handleBadLineImpl.

Parameters:

pBadLine - BadLine object describing problem

endProcess

public void endProcess()

Called just after loading of the CSV data ends.

You should use this method to release any resources used by your LineListener.

Implement by overriding CustomLineListener.endProcessImpl.

See Also:

startProcess()