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.

Author:

Glen Smith

Field Summary

Fields

Modifier and Type	Field and Description
protected BufferedReader	br
static boolean	DEFAULT_KEEP_CR
static int	DEFAULT_MULTILINE_LIMIT The default limit for the number of lines in a multiline record.
static int	DEFAULT_SKIP_LINES The default line to start reading.
static boolean	DEFAULT_VERIFY_READER
protected Locale	errorLocale
protected boolean	hasNext
protected boolean	keepCR
protected LineReader	lineReader
protected long	linesRead
protected boolean	linesSkipped
protected int	multilineLimit
protected ICSVParser	parser
protected static List<Class<? extends IOException>>	PASSTHROUGH_EXCEPTIONS
protected String[]	peekedLine
protected Queue<OrderedObject<String>>	peekedLines
static int	READ_AHEAD_LIMIT
protected long	recordsRead
protected int	skipLines
protected boolean	verifyReader

Constructor Summary

Constructors

Constructor and Description
CSVReader(Reader reader) Constructs CSVReader using defaults for all parameters.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the underlying reader.
protected String[]	combineResultsFromMultipleReads(String[] buffer, 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 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.
Iterator<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.
String[]	peek() Returns the next line from the input without removing it from the CSVReader and not running any validators.
List<String[]>	readAll() Reads the entire file into a List with each element being a String[] of tokens.
String[]	readNext() Reads the next line from the buffer and converts to a string array.
String[]	readNextSilently() Reads the next line from the buffer and converts to a string array without running the custom defined validators.
void	setErrorLocale(Locale errorLocale) Sets the locale for all error messages.
void	skip(int numberOfLinesToSkip) Skip a given number of lines.
protected void	validateResult(String[] result, long lineStartOfRow) 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_KEEP_CR

public static final boolean DEFAULT_KEEP_CR

See Also:

Constant Field Values

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 List<Class<? extends IOException>> PASSTHROUGH_EXCEPTIONS

READ_AHEAD_LIMIT

public static final int READ_AHEAD_LIMIT

See Also:

Constant Field Values

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

Constructor Detail

CSVReader

public CSVReader(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 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.

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 Closeable

Specified by:

close in interface AutoCloseable

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:

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 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