Class CSVReader
- All Implemented Interfaces:
Closeable
,AutoCloseable
,Iterable<String[]>
- Direct Known Subclasses:
CSVReaderHeaderAware
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected BufferedReader
(package private) static final int
static final boolean
static final int
The default limit for the number of lines in a multiline record.static final int
The default line to start reading.static final boolean
protected Locale
protected boolean
protected boolean
protected LineReader
protected long
protected boolean
private final LineValidatorAggregator
private static final int
protected int
protected ICSVParser
protected static final List
<Class<? extends IOException>> protected String[]
protected final Queue
<OrderedObject<String>> static final int
protected long
private final RowProcessor
private final RowValidatorAggregator
protected int
protected boolean
-
Constructor Summary
ConstructorsConstructorDescriptionConstructs CSVReader using defaults for all parameters.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. -
Method Summary
Modifier and TypeMethodDescriptionvoid
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).private String[]
flexibleRead
(boolean popLine, boolean validate) Reads a line of input, popping or validating as desired.long
This method returns the number of lines that has been read from the reader passed into the CSVReader.int
Only useful for tests.protected String
Reads the next line from the file.long
Used for debugging purposes, this method returns the number of records that has been read from the CSVReader.int
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()
Creates an Iterator for processing the CSV data.boolean
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.private void
Reads the next line from the buffer and converts to a string array.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[]
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.private void
validateLine
(long lastSuccessfulLineRead, String nextLine) Runs all line validators on the input.protected void
validateResult
(String[] result, long lineStartOfRow) Increments the number of records read if the result passed in is not null.boolean
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 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_LINESThe default line to start reading.- See Also:
-
DEFAULT_MULTILINE_LIMIT
public static final int DEFAULT_MULTILINE_LIMITThe default limit for the number of lines in a multiline record. Less than one means no limit.- See Also:
-
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
-
skipLines
protected int skipLines -
br
-
lineReader
-
hasNext
protected boolean hasNext -
linesSkipped
protected boolean linesSkipped -
keepCR
protected boolean keepCR -
verifyReader
protected boolean verifyReader -
multilineLimit
protected int multilineLimit -
errorLocale
-
linesRead
protected long linesRead -
recordsRead
protected long recordsRead -
peekedLine
-
peekedLines
-
lineValidatorAggregator
-
rowValidatorAggregator
-
rowProcessor
-
-
Constructor Details
-
CSVReader
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 sourceline
- The number of lines to skip before readingicsvParser
- The parser to use to parse inputkeepCR
- True to keep carriage returns in data read, false otherwiseverifyReader
- True to verify reader before each read, false otherwisemultilineLimit
- 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
- 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
Reads the entire file into a List with each element being a String[] of tokens. Since the current implementation returns aLinkedList
, 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 readCsvException
- If there is a failed validator
-
readNext
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 readCsvValidationException
- If a user-defined validator fails
-
readNextSilently
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
Reads the next line from the buffer and converts to a string array. The results are stored inpeekedLines
andpeekedLine
.- 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 messagesnextLine
- The input to be validated- Throws:
CsvValidationException
- Only thrown if a user-supplied validator throws it
-
validateResult
Increments the number of records read if the result passed in is not null.- Parameters:
result
- The result of the read operationlineStartOfRow
- Line number that the row started on- Throws:
CsvValidationException
- if there is a validation error caught by a custom RowValidator.
-
combineResultsFromMultipleReads
For multi-line records this method combines the current result with the result from previous read(s).- Parameters:
buffer
- Previous data read for this recordlastRead
- Latest data read for this record.- Returns:
- String array with union of the buffer and lastRead arrays.
-
getNextLine
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
Checks to see if the file is closed.Certain
IOException
s 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
- IfverifyReader()
was set totrue
certainIOException
s will still be passed out as they are indicative of a problem, not end of file.
-
close
Closes the underlying reader.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
- If the close fails
-
iterator
Creates an Iterator for processing the CSV data. -
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
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
Sets the locale for all error messages.- Parameters:
errorLocale
- Locale for error messages. If null, the default locale is used.- Since:
- 4.2
-
peek
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 toreadNext()
or any other method that advances the cursor position in the input. The first call toreadNext()
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 istrue
, this method consumes the line and further calls will return the next line of input. Iffalse
, 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 readingCsvValidationException
- If a user-supplied validator throws it
-