001package org.gbif.utils.file.tabular;
002
003import java.io.Closeable;
004import java.io.IOException;
005import java.util.List;
006
007/**
008 * Interface defining a reader for tabular data file (e.g. CSV)
009 */
010public interface TabularDataFileReader<T> extends Closeable {
011
012  /**
013   * Get the header line of the tabular data file (if possible).
014   *
015   * @return headers or null
016   */
017  List<String> getHeaderLine() throws IOException;
018
019  /**
020   * Read a non-empty line of the tabular data file.
021   * An empty line represents a line with no printable characters. A line with only the defined separators is
022   * expected to be returned.
023   *
024   * @return the next line of the tabular data file or null if the end of the file is reached.
025   *
026   * @throws IOException
027   */
028  T read() throws IOException;
029
030
031  /**
032   * The line number of where the last record returned by {@link #read()} starts.
033   * If no records have been returned yet this method is expected to return 0.
034   * Once {@link #read()} returned null, this methods will return the number of the last line in the file.
035   * Note that if the very last line is an empty line with only an endline character it will not be counted.
036   * Line number includes header line and empty lines (if applicable).
037   *
038   * @return line number of where the last record starts
039   */
040  long getLastRecordLineNumber();
041
042  /**
043   * Represents the number of record returned by the {@link #read()} method.
044   * If no records have been returned yet this method is expected to return 0.
045   * A record can span over multiple line.
046   *
047   * @return
048   */
049  long getLastRecordNumber();
050
051}