com.ricebridge.csvman
Class CustomLineProvider

java.lang.Object
  com.ricebridge.csvman.LineProviderSupportImpl
      com.ricebridge.csvman.CustomLineProvider

All Implemented Interfaces:

LineProvider

Direct Known Subclasses:

AsListsLineProvider, BasicLineProvider, BeanLineProvider, CsvHandlerTest.TestLineProvider, PerformanceTestFileMaker.RandomValueLineProvider, ResultSetLineProvider, Snippets.MyLineProvider, Snippets.NumbersLineProvider, Snippets.StringsProvider, TableModelLineProvider

public abstract class CustomLineProvider

extends LineProviderSupportImpl

Extend this class to create your own LineProvider.

You can export your data to CSV by overriding and implementing the methods in this class. You can do this when your source data must be accessed in a specific way and you need to control the exact data that is output. The basic idea is that you implement the hasNextLineImpl() and nextLineImpl methods. These are called each time a line of CSV data is to be saved. You then return a String[] array containing your own data that CSV Manager will output as the fields of the CSV data line.

Here's a very simple example. This LineProvider just creates a set of numbers to use as a data set. In your own projects, you'll probably source the data from a database or XML file, or other data storage system.

  public static class NumbersLineProvider extends CustomLineProvider {
    private int line = 0;
      
    protected boolean hasNextLineImpl() throws Exception {
      return line < 11;
    }
  
    protected String[] nextLineImpl() throws Exception {
      line++;
      return new String[] {""+line, ""+(10*line) };
    }   
  }
  

You can see from this code that instead of implementing the public LineProvider.hasNextLine and LineProvider.nextLine methods directly, you implement the protected hasNextLineImpl and nextLineImpl methods. This insulates you from API changes and also provides an extra layer of error checking. Also, CustomLineProvider provides default implementations for most of the methods of LineProvider, so hasNextLineImpl and nextLineImpl are the only ones you need to worry about.

Here's how you actually use this class:

    CsvManager           csvman = new CsvManager();
    NumbersLineProvider  nlp    = new NumbersLineProvider();
    csvManager.save( "output-file.csv", nlp );
  

You just create a new instance of NumbersLineProvider, and then pass it to CsvManager.

When using custom LineProviders, the only thing that is different from the normal save methods is that you do not pass in the data to the save method. You have to initialise your LineProvider with the data first.

For more information about implementing your own LineProviders, see the LineProvider interface documentation. Also, take a look at the other methods you can implement:

• setCsvSpecImpl
• setLineSpecImpl
• startProcessImpl
• endProcessImpl

Note: You can implement the LineProvider interface directly if you need to. The danger is that your implementation may not remain compatible with future versions of CSV Manager. And you lose all the extra error-handling. So it's better to stick with extending CustomLineProvider if you can.

Finally, if you want to load data with custom processing, see LineListener.

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

Since:

1.2.1

See Also:

LineProvider, LineProviderSupportImpl, BasicLineProvider, CsvManager, CsvManagerException

Constructor Summary

CustomLineProvider()

Method Summary

protected void	endProcessImpl() Implement this method to receive notification that the saving of CSV data has ended.
protected abstract boolean	hasNextLineImpl() Implement this method to let CSV Manager know that there is another line of data to save.
protected abstract String[]	nextLineImpl() Implement this method to supply each data line as it is saved.
protected void	setCsvSpecImpl(CsvSpec pCsvSpec) Set the current CsvSpec used for saving CSV files.
protected void	setLineSpecImpl(LineSpec pLineSpec) Set the current LineSpec used for interpreting CSV data fields.
protected void	startProcessImpl() Implement this method to receive notification that the saving of CSV data is about to start.

Methods inherited from class com.ricebridge.csvman.LineProviderSupportImpl

endProcess, hasNextLine, nextLine, setCsvSpec, setLineSpec, startProcess

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CustomLineProvider

public CustomLineProvider()

Method Detail

setCsvSpecImpl

protected void setCsvSpecImpl(CsvSpec pCsvSpec)
                       throws Exception

Set the current CsvSpec used for saving CSV files.

You can implement this method when you extend CustomLineProvider, but it is not required.

The CsvSpec controls the CSV loading and saving process. It contains a number of settings such as the data field and line separators. You can also set your own custom settings using the CsvSpec.setProperty method. You can then access these settings inside your own LineProvider using the CsvSpec object passed into this method.

This method is called before setLineSpecImpl is called.

Specified by:

setCsvSpecImpl in class LineProviderSupportImpl

Parameters:

pCsvSpec - CsvSpec object

Throws:

Exception

See Also:

CsvSpec, setLineSpecImpl

setLineSpecImpl

protected void setLineSpecImpl(LineSpec pLineSpec)
                        throws Exception

Set the current LineSpec used for interpreting CSV data fields.

You can implement this method when you extend CustomLineProvider, but it is not required.

The LineSpec controls the conversion of internal data into individual CSV data fields. Whereas CsvSpec controls the entire process, LineSpec only applies to each data field. In the current version of CSV Manager (1.2), LineSpec is used to load and save Java Beans, by providing the get and set method names for each data field. See BeanLineProvider for more details.

You can subclass LineSpec to add your own data field specific information for your own custom LineProviders. You can then access these settings inside your own LineProvider using the LineSpec object passed into this method.

This method is called after setCsvSpecImpl is called.

Specified by:

setLineSpecImpl in class LineProviderSupportImpl

Parameters:

pLineSpec - LineSpec object

Throws:

Exception

See Also:

LineSpec, setCsvSpecImpl, BeanLineProvider

startProcessImpl

protected void startProcessImpl()
                         throws Exception

Implement this method to receive notification that the saving of CSV data is about to start.

You can implement this method when you extend CustomLineProvider, but it is not required.

You can use this method to initialise any resource you need to process the CSV data. For example you can open a database connection to retrieve the data as it is saved.

This method is called after setCsvSpecImpl and setLineSpecImpl.

Specified by:

startProcessImpl in class LineProviderSupportImpl

Throws:

Exception

See Also:

endProcessImpl

hasNextLineImpl

protected abstract boolean hasNextLineImpl()
                                    throws Exception

Implement this method to let CSV Manager know that there is another line of data to save.

This method must be implemented when you extend CustomLineProvider.

Return true from this method so long as you have more data lines to save.

Specified by:

hasNextLineImpl in class LineProviderSupportImpl

Throws:

Exception

See Also:

LineProvider.hasNextLine, nextLineImpl

nextLineImpl

protected abstract String[] nextLineImpl()
                                  throws Exception

Implement this method to supply each data line as it is saved.

This method must be implemented when you extend CustomLineProvider.

This method is where you will do the main work of providing the CSV data. Each time this method is called you will need to provide a new line of CSV data as a String[] array.

Error Handling: What happens when you cannot provide the line data for some reason? For example your database connection may fail. In this case, all you have to do is throw an Exception to let CSV Manager know about the problem. But note that if the CsvSpec.setIgnoreBadLines setting is true, then CSV Manager will not stop asking you for more data lines until you also return false from hasNextLineImpl().

Specified by:

nextLineImpl in class LineProviderSupportImpl

Throws:

Exception

See Also:

LineProvider.nextLine, hasNextLineImpl

endProcessImpl

protected void endProcessImpl()
                       throws Exception

Implement this method to receive notification that the saving of CSV data has ended.

You can implement this method when you extend CustomLineProvider, but it is not required.

You can use this method to close any open resources that were used to handle the CSV data. For example you can close any open database connections.

This method is called last, after all hasNextLineImpl and nextLineImpl calls have been made.

Specified by:

endProcessImpl in class LineProviderSupportImpl

Throws:

Exception

See Also:

startProcessImpl