Package com.opencsv

Class CSVReader

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, java.lang.Iterable<java.lang.String[]>
    Direct Known Subclasses:
    CSVReaderHeaderAware
    public class CSVReader
extends java.lang.Object
implements java.io.Closeable, java.lang.Iterable<java.lang.String[]>
    A very simple CSV reader released under a commercial-friendly license.
    Author:
    Glen Smith

    • Constructor Summary

      Constructors 
      Constructor Description
      CSVReader​(java.io.Reader reader)
      Constructs CSVReader using defaults for all parameters.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Closes the underlying reader.
      protected java.lang.String[] combineResultsFromMultipleReads​(java.lang.String[] buffer, java.lang.String[] lastRead)
      For multi-line records this method combines the current result with the result from previous read(s).
      long getLinesRead()
      This method returns the number of lines that has been read from the reader passed into the CSVReader.
      int getMultilineLimit()
      Only useful for tests.
      protected java.lang.String getNextLine()
      Reads the next line from the file.
      ICSVParser getParser()  
      long getRecordsRead()
      Used for debugging purposes, this method returns the number of records that has been read from the CSVReader.
      int getSkipLines()
      Returns the number of lines in the CSV file to skip before processing.
      protected boolean isClosed()
      Checks to see if the file is closed.
      java.util.Iterator<java.lang.String[]> iterator()
      Creates an Iterator for processing the CSV data.
      boolean keepCarriageReturns()
      Returns if the reader will keep carriage returns found in data or remove them.
      java.lang.String[] peek()
      Returns the next line from the input without removing it from the CSVReader and not running any validators.
      java.util.List<java.lang.String[]> readAll()
      Reads the entire file into a List with each element being a String[] of tokens.
      java.lang.String[] readNext()
      Reads the next line from the buffer and converts to a string array.
      java.lang.String[] readNextSilently()
      Reads the next line from the buffer and converts to a string array without running the custom defined validators.
      void setErrorLocale​(java.util.Locale errorLocale)
      Sets the locale for all error messages.
      void skip​(int numberOfLinesToSkip)
      Skip a given number of lines.
      protected java.lang.String[] validateResult​(java.lang.String[] result, long lineStartOfRow, boolean useRowValidators)
      Increments the number of records read if the result passed in is not null.
      boolean verifyReader()
      Returns if the CSVReader will verify the reader before each read.

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Field Detail

      • DEFAULT_VERIFY_READER

        public static final boolean DEFAULT_VERIFY_READER
        See Also:
        Constant Field Values

      • DEFAULT_SKIP_LINES

        public static final int DEFAULT_SKIP_LINES
        The default line to start reading.
        See Also:
        Constant Field Values

      • 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:
        Constant Field Values

      • PASSTHROUGH_EXCEPTIONS

        protected static final java.util.List<java.lang.Class<? extends java.io.IOException>> PASSTHROUGH_EXCEPTIONS

      • skipLines

        protected int skipLines

      • br

        protected java.io.BufferedReader br

      • hasNext

        protected boolean hasNext

      • linesSkipped

        protected boolean linesSkipped

      • keepCR

        protected boolean keepCR

      • verifyReader

        protected boolean verifyReader

      • multilineLimit

        protected int multilineLimit

      • errorLocale

        protected java.util.Locale errorLocale

      • linesRead

        protected long linesRead

      • recordsRead

        protected long recordsRead

      • peekedLine

        protected java.lang.String[] peekedLine

    • Constructor Detail

      • CSVReader

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

    • Method Detail

      • 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 java.util.List<java.lang.String[]> readAll()
                                           throws java.io.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:
        java.io.IOException - If bad things happen during the read
        CsvException - - if there is a failed validator.

      • readNext

        public java.lang.String[] readNext()
                            throws java.io.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:
        java.io.IOException - If bad things happen during the read
        CsvValidationException - If a user-defined validator fails

      • readNextSilently

        public java.lang.String[] readNextSilently()
                                    throws java.io.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:
        java.io.IOException - If bad things happen during the read.

      • validateResult

        protected java.lang.String[] validateResult​(java.lang.String[] result,
                                            long lineStartOfRow,
                                            boolean useRowValidators)
                                     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
        useRowValidators - Run custom defined row validators, if any exists.
        Returns:
        Result that was passed in.
        Throws:
        CsvValidationException - if there is a validation error caught by a custom RowValidator.

      • combineResultsFromMultipleReads

        protected java.lang.String[] combineResultsFromMultipleReads​(java.lang.String[] buffer,
                                                             java.lang.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 java.lang.String getNextLine()
                                throws java.io.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:
        java.io.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 java.io.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 excpetions are:

        CharacterCodingException CharConversionException FileNotFoundException UnsupportedEncodingException UTFDataFormatException ZipException MalformedInputException

        Returns:
        True if the reader can no longer be read from.
        Throws:
        java.io.IOException - - if verified reader is true certain IOExceptions will still be passed out as they are indicative of a problem not end of file.

      • close

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

      • iterator

        public java.util.Iterator<java.lang.String[]> iterator()
        Creates an Iterator for processing the CSV data.
        Specified by:
        iterator in interface java.lang.Iterable<java.lang.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:
        Bug 108

      • 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:
        Feature Request 73

      • skip

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

      • setErrorLocale

        public void setErrorLocale​(java.util.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 java.lang.String[] peek()
                        throws java.io.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:
        java.io.IOException - If bad things happen during the read operation
        Since:
        4.2