com.ricebridge.csvman
Interface CsvLoader

All Known Implementing Classes:

BasicCsvLoader

public interface CsvLoader

Load CSV data lines as you need them.

This interface allows you to load CSV data lines as a stream of data, one at a time. Instead of loading an entire CSV file, as with the CsvManager.load method, or implementing a CustomLineListener, CsvLoader lets you access the data directly using Iterator-style hasNext and next methods.

To start a loading operation, use the CsvManager.makeLoader method. This returns a CsvLoader object. Then use the following sequence of method calls:

• begin() - required, tells the CsvLoader to open the data resource (usually a CSV file on disk)
• hasNext() - required, returns true if there's another line of data left
• next() - required, returns the next line of data as a String[] array
• end() - required, tells the CsvLoader to close the data resource (usually a CSV file on disk)

Here is some example code:

  File       csvfile = new File( "mydata.csv" );
  CsvManager csvman  = new CsvManager();
  CsvLoader  loader  = csvman.makeLoader( csvfile );

  loader.begin();
  while( loader.hasNext() ) {
    String[] fields = loader.next();

    for( int field = 0; field < fields.length; field++ ) {
      System.out.print( fields[field]+", " );
    }
    System.out.println();
  }
  loader.end();
  

Because only one line is read at a time, you can use CsvLoader to load really big CSV files without running out of memory.

Why does CsvLoader have begin() and end() methods and why do you need to call them? Good question! Unlike the other ways of loading CSV data provided by CSV Manager, when you use a CsvLoader, you control the loading process. That means you control how often a new data line is extracted from the CSV file. And you control when the loading process begins and ends. You can begin the loading process sometime after you actually create the CsvLoader, and you can end it at any time, without having to load the entire file.

Error Handling: if the CSV file contains a badly-formatted line, then a CsvManagerException will be thrown from the next() method. If the setIgnoreBadLines setting is true, then you can continue to call hasNext() and next() after a bad line Exception. You just have to deal with the Exception yourself. Note that each data line is actually read in the hasNext method and stored for retrieval from the next method.

If you also want to save CSV data one line at a time, check out the CsvSaver class, which works in pretty much the same way as CsvLoader.

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

Since:

1.2.1

See Also:

CsvSaver, LineListener, CsvManager.load(Object)

Method Summary

void	begin() Tell the CsvLoader you want to begin the loading process.
void	end() Tell the CsvLoader you want to end the loading process.
boolean	hasNext() Check if there's another line of data in the CSV file, and return true if so.
String[]	next() Get the next line of data as a String[] array.

Method Detail

begin

public void begin()

Tell the CsvLoader you want to begin the loading process.

This is where the CSV file input stream is opened for reading.

hasNext

public boolean hasNext()

Check if there's another line of data in the CSV file, and return true if so.

Note: this method actually has to load the next line of data to know if there is one, so this method is where data is read from the CSV file. You can get the line of data using the next() method.

next

public String[] next()

Get the next line of data as a String[] array.

CsvLoader always returns the data as a String[] array. To get the data into another format, you will have to convert the data yourself. For example, you can use the utility classes CsvResultSet and CsvTableModel to create ResultSets and TableModels. Review the source code of the appropriate LineListener to see how they are used.

The length of the String[] array returned by this method will be at least CsvSpec.setNumFields elements. If longer lines are encountered, then the array will be as long as the longest line seen so far. Empty fields at the end are returned as empty Strings. This approach prevents ArrayIndexOutOfBoundsException and NullPointerException errors. However, if you do need to know the exact number of data fields in any given CSV line then you should use a CustomLineListener instead, which provides more information about each line.

Error Handling: when an error occurs, this method always throws a CsvManagerException. The details of the bad line are available via the CsvManagerException.getBadLine method. An exception is also thrown even if CsvSpec.setIgnoreBadLines is set to true. However in this case you can continue to call hasNext() and next to get the remaining good lines and you are not required to stop processing.

end

public void end()

Tell the CsvLoader you want to end the loading process.

This is where the CSV file input stream is closed.