Package com.opencsv

Class CSVReader

java.lang.Object
com.opencsv.CSVReader
All Implemented Interfaces:
Closeable, AutoCloseable, Iterable<String[]>
Direct Known Subclasses:
CSVReaderHeaderAware

public class CSVReader extends Object implements Closeable, Iterable<String[]>
A very simple CSV reader released under a commercial-friendly license.
  • Field Details

    • DEFAULT_KEEP_CR

      public static final boolean DEFAULT_KEEP_CR
      See Also:
    • DEFAULT_VERIFY_READER

      public static final boolean DEFAULT_VERIFY_READER
      See Also:
    • CONTEXT_MULTILINE_EXCEPTION_MESSAGE_SIZE

      static final int CONTEXT_MULTILINE_EXCEPTION_MESSAGE_SIZE
      See Also:
    • DEFAULT_SKIP_LINES

      public static final int DEFAULT_SKIP_LINES
      The default line to start reading.
      See Also:
    • DEFAULT_MULTILINE_LIMIT

      public static final int DEFAULT_MULTILINE_LIMIT
      The default limit for the number of lines in a multiline record. Less than one means no limit.
      See Also:
    • PASSTHROUGH_EXCEPTIONS

      protected static final List<Class<? extends IOException>> PASSTHROUGH_EXCEPTIONS
    • READ_AHEAD_LIMIT

      public static final int READ_AHEAD_LIMIT
      See Also:
    • MAX_WIDTH

      private static final int MAX_WIDTH
      See Also:
    • parser

      protected ICSVParser parser
    • skipLines

      protected int skipLines
    • br

      protected BufferedReader br
    • lineReader

      protected LineReader lineReader
    • hasNext

      protected boolean hasNext
    • linesSkipped

      protected boolean linesSkipped
    • keepCR

      protected boolean keepCR
    • verifyReader

      protected boolean verifyReader
    • multilineLimit

      protected int multilineLimit
    • errorLocale

      protected Locale errorLocale
    • linesRead

      protected long linesRead
    • recordsRead

      protected long recordsRead
    • peekedLine

      protected String[] peekedLine
    • peekedLines

      protected final Queue<OrderedObject<String>> peekedLines
    • lineValidatorAggregator

      private final LineValidatorAggregator lineValidatorAggregator
    • rowValidatorAggregator

      private final RowValidatorAggregator rowValidatorAggregator
    • rowProcessor

      private final RowProcessor rowProcessor
  • Constructor Details

    • CSVReader

      public CSVReader(Reader reader)
      Constructs CSVReader using defaults for all parameters.
      Parameters:
      reader - The reader to an underlying CSV source.
    • CSVReader

      CSVReader(Reader reader, int line, ICSVParser icsvParser, boolean keepCR, boolean verifyReader, int multilineLimit, Locale errorLocale, LineValidatorAggregator lineValidatorAggregator, RowValidatorAggregator rowValidatorAggregator, RowProcessor rowProcessor)
      Constructs CSVReader with supplied CSVParser.

      This constructor sets all necessary parameters for CSVReader, and intentionally has package access so only the builder can use it.

      Parameters:
      reader - The reader to an underlying CSV source
      line - The number of lines to skip before reading
      icsvParser - The parser to use to parse input
      keepCR - True to keep carriage returns in data read, false otherwise
      verifyReader - True to verify reader before each read, false otherwise
      multilineLimit - Allow the user to define the limit to the number of lines in a multiline record. Less than one means no limit.
      errorLocale - Set the locale for error messages. If null, the default locale is used.
      lineValidatorAggregator - contains all the custom defined line validators.
      rowValidatorAggregator - contains all the custom defined row validators.
      rowProcessor - Custom row processor to run on all columns on a csv record.
  • Method Details

    • getParser

      public ICSVParser getParser()
      Returns:
      The CSVParser used by the reader.
    • getSkipLines

      public int getSkipLines()
      Returns the number of lines in the CSV file to skip before processing. This is useful when there are miscellaneous data at the beginning of a file.
      Returns:
      The number of lines in the CSV file to skip before processing.
    • keepCarriageReturns

      public boolean keepCarriageReturns()
      Returns if the reader will keep carriage returns found in data or remove them.
      Returns:
      True if reader will keep carriage returns, false otherwise.
    • readAll

      public List<String[]> readAll() throws IOException, CsvException
      Reads the entire file into a List with each element being a String[] of tokens. Since the current implementation returns a LinkedList, you are strongly discouraged from using index-based access methods to get at items in the list. Instead, iterate over the list.
      Returns:
      A List of String[], with each String[] representing a line of the file.
      Throws:
      IOException - If bad things happen during the read
      CsvException - If there is a failed validator
    • readNext

      public String[] readNext() throws IOException, CsvValidationException
      Reads the next line from the buffer and converts to a string array.
      Returns:
      A string array with each comma-separated element as a separate entry, or null if there is no more input.
      Throws:
      IOException - If bad things happen during the read
      CsvValidationException - If a user-defined validator fails
    • readNextSilently

      public String[] readNextSilently() throws IOException
      Reads the next line from the buffer and converts to a string array without running the custom defined validators. This is called by the bean readers when reading the header.
      Returns:
      A string array with each comma-separated element as a separate entry, or null if there is no more input.
      Throws:
      IOException - If bad things happen during the read.
    • primeNextRecord

      private void primeNextRecord() throws IOException
      Reads the next line from the buffer and converts to a string array. The results are stored in peekedLines and peekedLine.
      Throws:
      IOException - If bad things happen during the read
    • validateLine

      private void validateLine(long lastSuccessfulLineRead, String nextLine) throws CsvValidationException
      Runs all line validators on the input.
      Parameters:
      lastSuccessfulLineRead - The line number for error messages
      nextLine - The input to be validated
      Throws:
      CsvValidationException - Only thrown if a user-supplied validator throws it
    • validateResult

      protected void validateResult(String[] result, long lineStartOfRow) throws CsvValidationException
      Increments the number of records read if the result passed in is not null.
      Parameters:
      result - The result of the read operation
      lineStartOfRow - Line number that the row started on
      Throws:
      CsvValidationException - if there is a validation error caught by a custom RowValidator.
    • combineResultsFromMultipleReads

      protected String[] combineResultsFromMultipleReads(String[] buffer, String[] lastRead)
      For multi-line records this method combines the current result with the result from previous read(s).
      Parameters:
      buffer - Previous data read for this record
      lastRead - Latest data read for this record.
      Returns:
      String array with union of the buffer and lastRead arrays.
    • getNextLine

      protected String getNextLine() throws IOException
      Reads the next line from the file.
      Returns:
      The next line from the file without trailing newline, or null if there is no more input.
      Throws:
      IOException - If bad things happen during the read
    • getMultilineLimit

      public int getMultilineLimit()
      Only useful for tests.
      Returns:
      The maximum number of lines allowed in a multiline record.
    • isClosed

      protected boolean isClosed() throws IOException
      Checks to see if the file is closed.

      Certain IOExceptions will be passed out, as they are indicative of a real problem, not that the file has already been closed. These exceptions are:

      • CharacterCodingException
      • CharConversionException
      • FileNotFoundException
      • UnsupportedEncodingException
      • UTFDataFormatException
      • ZipException
      • MalformedInputException

      Returns:
      true if the reader can no longer be read from
      Throws:
      IOException - If verifyReader() was set to true certain IOExceptions will still be passed out as they are indicative of a problem, not end of file.
    • close

      public void close() throws IOException
      Closes the underlying reader.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - If the close fails
    • iterator

      public Iterator<String[]> iterator()
      Creates an Iterator for processing the CSV data.
      Specified by:
      iterator in interface Iterable<String[]>
      Returns:
      A String[] iterator.
    • verifyReader

      public boolean verifyReader()
      Returns if the CSVReader will verify the reader before each read.

      By default the value is true, which is the functionality for version 3.0. If set to false the reader is always assumed ready to read - this is the functionality for version 2.4 and before.

      The reason this method was needed was that certain types of readers would return false for their ready() methods until a read was done (namely readers created using Channels). This caused opencsv not to read from those readers.

      Returns:
      True if CSVReader will verify the reader before reads. False otherwise.
      Since:
      3.3
      See Also:
    • getLinesRead

      public long getLinesRead()
      This method returns the number of lines that has been read from the reader passed into the CSVReader.

      Given the following data:

       First line in the file
       some other descriptive line
       a,b,c
      
       a,"b\nb",c
       

      With a CSVReader constructed like so:
      CSVReader c = builder.withCSVParser(new CSVParser())
      .withSkipLines(2)
      .build();

      The initial call to getLinesRead() will be 0. After the first call to readNext() then getLinesRead() will return 3 (because the header was read). After the second call to read the blank line then getLinesRead() will return 4 (still a read). After the third call to readNext(), getLinesRead() will return 6 because it took two line reads to retrieve this record. Subsequent calls to readNext() (since we are out of data) will not increment the number of lines read.

      Returns:
      The number of lines read by the reader (including skipped lines).
      Since:
      3.6
    • getRecordsRead

      public long getRecordsRead()
      Used for debugging purposes, this method returns the number of records that has been read from the CSVReader.

      Given the following data:

       First line in the file
       some other descriptive line
       a,b,c
       a,"b\nb",c
       

      With a CSVReader constructed like so:
      CSVReader c = builder.withCSVParser(new CSVParser())
      .withSkipLines(2)
      .build();

      The initial call to getRecordsRead() will be 0. After the first call to readNext() then getRecordsRead() will return 1. After the second call to read the blank line then getRecordsRead() will return 2 (a blank line is considered a record with one empty field). After third call to readNext() getRecordsRead() will return 3 because even though it reads to retrieve this record, it is still a single record read. Subsequent calls to readNext() (since we are out of data) will not increment the number of records read.

      An example of this is in the linesAndRecordsRead() test in CSVReaderTest.

      Returns:
      The number of records (array of Strings[]) read by the reader.
      Since:
      3.6
      See Also:
    • skip

      public void skip(int numberOfLinesToSkip) throws IOException
      Skip a given number of lines.
      Parameters:
      numberOfLinesToSkip - The number of lines to skip
      Throws:
      IOException - If anything bad happens when reading the file
      Since:
      4.2
    • setErrorLocale

      public void setErrorLocale(Locale errorLocale)
      Sets the locale for all error messages.
      Parameters:
      errorLocale - Locale for error messages. If null, the default locale is used.
      Since:
      4.2
    • peek

      public String[] peek() throws IOException
      Returns the next line from the input without removing it from the CSVReader and not running any validators. Subsequent calls to this method will continue to return the same line until a call is made to readNext() or any other method that advances the cursor position in the input. The first call to readNext() after calling this method will return the same line this method does.
      Returns:
      The next line from the input, or null if there are no more lines
      Throws:
      IOException - If bad things happen during the read operation
      Since:
      4.2
    • flexibleRead

      private String[] flexibleRead(boolean popLine, boolean validate) throws IOException, CsvValidationException
      Reads a line of input, popping or validating as desired.
      Parameters:
      popLine - Whether the line returned should be popped off the queue of input. If this is true, this method consumes the line and further calls will return the next line of input. If false, the line returned stays in the queue and further calls to this method will return the same line again.
      validate - Whether all user-supplied validators should be run.
      Returns:
      The next line of input
      Throws:
      IOException - If this exception is thrown while reading
      CsvValidationException - If a user-supplied validator throws it