Class CsvProcessor<T>

java.lang.Object
com.j256.simplecsv.processor.CsvProcessor<T>
Type Parameters:
T - Entity type that we are processing. It should have a public no-arg constructor so it can be created by this library.
public class CsvProcessor<T> extends Object
CSV reader and writer.

NOTE: You need to set the entity class either in the constructor, with setEntityClass(Class), or withEntityClass(Class). Then you need to do any registerConverter(Class, Converter) or withConverter(Class, Converter) calls before the processor gets configured. You can then let the processor be auto-configured on the first read/write method call or call initialize() directly (or in spring).

Author:
graywatson

  • Field Details

    • DEFAULT_COLUMN_SEPARATOR

      public static final char DEFAULT_COLUMN_SEPARATOR
      Default separator character for columns. This can be changed with setColumnSeparator(char).
      See Also:

    • DEFAULT_COLUMN_QUOTE

      public static final char DEFAULT_COLUMN_QUOTE
      Default quote character for columns to wrap them if they have special characters. This can be changed with setColumnQuote(char).
      See Also:

    • DEFAULT_LINE_TERMINATION

      public static final String DEFAULT_LINE_TERMINATION
      Default line termination string to be written at the end of CSV lines. This can be changed with setLineTermination(String).

  • Constructor Details

    • CsvProcessor

      public CsvProcessor()

    • CsvProcessor

      public CsvProcessor(Class<T> entityClass)
      Constructs a processor with an entity class whose fields should be marked with CsvColumn annotations. The entity-class must also define a public no-arg contructor so the processor can instantiate them using reflection.

  • Method Details

    • registerConverter

      public <FT> void registerConverter(Class<FT> clazz, Converter<FT,?> converter)
      Register a converter class for all instances of the class argument. The converter can also be specified with the CsvColumn.converterClass() annotation field.

    • withConverter

      public <FT> CsvProcessor<T> withConverter(Class<FT> clazz, Converter<FT,?> converter)
      Register a converter class for all instances of the class argument. The converter can also be specified with the CsvColumn.converterClass() annotation field. Alternative way to do registerConverter(Class, Converter).

    • initialize

      public CsvProcessor<T> initialize()
      This initializing the internal configuration information. It will self initialize if you start calling read/write methods but this is here if you are using the class concurrently and need to force the initialization.

    • readAll

      public List<T> readAll(String filePath, Collection<ParseError> parseErrors) throws ParseException, IOException
      Read in all of the entities in the file passed in.
      Parameters:
      filePath - Where to read the header and entities from.
      parseErrors - If not null, any errors will be added to the collection and null will be returned. If validateHeader is true and the header does not match then no additional lines will be returned. If this is null then a ParseException will be thrown on parsing problems.
      Returns:
      A list of entities read in or null if validateHeader is true and the first-line header was not valid.
      Throws:
      ParseException - Thrown on any parsing problems. If parseErrors is not null then parse errors will be added there and an exception should not be thrown.
      IOException - If there are any IO exceptions thrown when reading.

    • readAll

      public List<T> readAll(File file, Collection<ParseError> parseErrors) throws ParseException, IOException
      Read in all of the entities in the file passed in.
      Parameters:
      file - Where to read the header and entities from.
      parseErrors - If not null, any errors will be added to the collection and null will be returned. If validateHeader is true and the header does not match then no additional lines will be returned. If this is null then a ParseException will be thrown on parsing problems.
      Returns:
      A list of entities read in or null if validateHeader is true and the first-line header was not valid.
      Throws:
      ParseException - Thrown on any parsing problems. If parseErrors is not null then parse errors will be added there and an exception should not be thrown.
      IOException - If there are any IO exceptions thrown when reading.

    • readAll

      public List<T> readAll(Reader reader, Collection<ParseError> parseErrors) throws ParseException, IOException
      Read in all of the entities in the reader passed in. It will use an internal buffered reader that tracks line numbers.
      Parameters:
      reader - Where to read the header and entities from. NOTE: It must be closed by the caller.
      parseErrors - If not null, any errors will be added to the collection and null will be returned. If validateHeader is true and the header does not match then no additional lines will be returned. If this is null then a ParseException will be thrown on parsing problems.
      Returns:
      A list of entities read in or null if parseErrors is not null.
      Throws:
      ParseException - Thrown on any parsing problems. If parseErrors is not null then parse errors will be added there and an exception should not be thrown.
      IOException - If there are any IO exceptions thrown when reading.

    • readHeader

      public String[] readHeader(BufferedReader bufferedReader, ParseError parseError) throws ParseException, IOException
      Read in a line and process it as a CSV header.
      Parameters:
      bufferedReader - Where to read the header from. It needs to be closed by the caller. Consider using BufferedReaderLineCounter to populate the line-number for parse errors.
      parseError - If not null, this will be set with the first parse error and it will return null. If this is null then a ParseException will be thrown instead.
      Returns:
      Array of header column names or null on error.
      Throws:
      ParseException - Thrown on any parsing problems. If parseError is not null then the error will be added there and an exception should not be thrown.
      IOException - If there are any IO exceptions thrown when reading.

    • readRows

      public List<T> readRows(BufferedReader bufferedReader, Collection<ParseError> parseErrors) throws ParseException, IOException
      Read in all of the entities in the reader passed in but without the header.
      Parameters:
      bufferedReader - Where to read the entries from. It needs to be closed by the caller. Consider using BufferedReaderLineCounter to populate the line-number for parse errors.
      parseErrors - If not null, any errors will be added to the collection and null will be returned. If validateHeader is true and the header does not match then no additional lines will be returned. If this is null then a ParseException will be thrown on parsing problems.
      Returns:
      A list of entities read in or null if parseErrors is not null.
      Throws:
      ParseException - Thrown on any parsing problems. If parseErrors is not null then parse errors will be added there and an exception should not be thrown.
      IOException - If there are any IO exceptions thrown when reading.

    • readRow

      public T readRow(BufferedReader bufferedReader, ParseError parseError) throws ParseException, IOException
      Read an entity line from the reader.
      Parameters:
      bufferedReader - Where to read the row from. It needs to be closed by the caller. Consider using BufferedReaderLineCounter to populate the line-number for parse errors.
      parseError - If not null, this will be set with the first parse error and it will return null. If this is null then a ParseException will be thrown instead.
      Returns:
      Entity read in or null on EOF or error. Check ParseError.isError() to see if it was an error or EOF.
      Throws:
      ParseException - Thrown on any parsing problems. If parseError is not null then the error will be added there and an exception should not be thrown.
      IOException - If there are any IO exceptions thrown when reading.

    • validateHeader

      public boolean validateHeader(String line, ParseError parseError) throws ParseException
      Validate the header row against the configured header columns.
      Parameters:
      line - Line to process to get our validate our header.
      parseError - If not null, this will be set with the first parse error and it will return null. If this is null then a ParseException will be thrown instead.
      Returns:
      true if the header matched the column names configured here otherwise false.
      Throws:
      ParseException - Thrown on any parsing problems. If parseError is not null then the error will be added there and an exception should not be thrown.

    • validateHeaderColumns

      public boolean validateHeaderColumns(String[] columns, ParseError parseError)
      Validate header columns returned by processHeader(String, ParseError).
      Parameters:
      columns - Array of columns to validate.
      parseError - If not null, this will be set with the first parse error and it will return null. If this is null then a ParseException will be thrown instead.
      Returns:
      true if the header matched the column names configured here otherwise false.
      Throws:
      ParseException - Thrown on any parsing problems. If parseError is not null then the error will be added there and an exception should not be thrown.

    • processHeader

      public String[] processHeader(String line, ParseError parseError) throws ParseException
      Process a header line and divide it up into a series of quoted columns.
      Parameters:
      line - Line to process looking for header.
      parseError - If not null, this will be set with the first parse error and it will return null. If this is null then a ParseException will be thrown instead.
      Returns:
      Returns an array of processed header names entity or null if an error and parseError has been set. The array will be the same length as the number of configured columns so some elements may be null.
      Throws:
      ParseException - Thrown on any parsing problems. If parseError is not null then the error will be added there and an exception should not be thrown.

    • processRow

      public T processRow(String line, ParseError parseError) throws ParseException
      Read and process a line and return the associated entity.
      Parameters:
      line - to process to build our entity.
      parseError - If not null, this will be set with the first parse error and it will return null. If this is null then a ParseException will be thrown instead.
      Returns:
      Returns a processed entity or null if an error and parseError has been set.
      Throws:
      ParseException - Thrown on any parsing problems. If parseError is not null then the error will be added there and an exception should not be thrown.

    • writeAll

      public void writeAll(String filePath, Collection<T> entities, boolean writeHeader) throws IOException
      Write a collection of entities to the writer.
      Parameters:
      filePath - Where to write the header and entities.
      entities - Collection of entities to write to the writer.
      writeHeader - Set to true to write header at the start of the output file.
      Throws:
      IOException - If there are any IO exceptions thrown when writing.

    • writeAll

      public void writeAll(File file, Collection<T> entities, boolean writeHeader) throws IOException
      Write a collection of entities to the writer.
      Parameters:
      file - Where to write the header and entities.
      entities - Collection of entities to write to the writer.
      writeHeader - Set to true to write header at the start of the output file.
      Throws:
      IOException - If there are any IO exceptions thrown when writing.

    • writeAll

      public void writeAll(Writer writer, Collection<T> entities, boolean writeHeader) throws IOException
      Write an optional header and then the collection of entities to the writer. NOTE: it is up to the caller to close the writer.
      Parameters:
      writer - Where to write the header and entities. NOTE: It must be closed by the caller.
      entities - Collection of entities to write to the writer.
      writeHeader - Set to true to write header at the start of the writer.
      Throws:
      IOException - If there are any IO exceptions thrown when writing.

    • writeHeader

      public void writeHeader(Writer writer, boolean appendLineTermination) throws IOException
      Write the header line to the writer.
      Parameters:
      writer - Where to write our header information.
      appendLineTermination - Set to true to add the newline to the end of the line.
      Throws:
      IOException - If there are any IO exceptions thrown when writing.

    • writeRow

      public void writeRow(Writer writer, T entity, boolean appendLineTermination) throws IOException
      Write an entity row to the writer.
      Parameters:
      writer - Where to write the row.
      entity - The entity we are writing to the buffered writer.
      appendLineTermination - Set to true to add the newline to the end of the line.
      Throws:
      IOException - If there are any IO exceptions thrown when writing.

    • buildHeaderLine

      public String buildHeaderLine(boolean appendLineTermination)
      Build and return a header string made up of quoted column names.
      Parameters:
      appendLineTermination - Set to true to add the newline to the end of the line.

    • buildLine

      public String buildLine(T entity, boolean appendLineTermination)
      Convert the entity into a string of column values.
      Parameters:
      appendLineTermination - Set to true to add the newline to the end of the line.

    • setEntityClass

      public void setEntityClass(Class<T> entityClass)
      Class that we are processing.

    • withEntityClass

      public CsvProcessor<T> withEntityClass(Class<T> entityClass)
      Class that we are processing. Alternative way to do setEntityClass(Class).

    • setConstructorCallable

      public void setConstructorCallable(Callable<T> constructorCallable)
      Set the a method that will construct the entity we are loading. This is used in case there are is not a no-arg constructor for the entity.

    • withConstructorCallable

      public CsvProcessor<T> withConstructorCallable(Callable<T> constructorCallable)
      Set the a method that will construct the entity we are loading. This is used in case there are is not a no-arg constructor for the entity. Alternative way to do setConstructorCallable(Callable).

    • setColumnSeparator

      public void setColumnSeparator(char columnSeparator)
      String that separates columns in out CSV input and output.

    • withColumnSeparator

      public CsvProcessor<T> withColumnSeparator(char columnSeparator)
      String that separates columns in out CSV input and output. Alternative way to do setColumnSeparator(char).

    • setColumnQuote

      public void setColumnQuote(char columnQuote)
      Quote character that is used to wrap each column.

    • withColumnQuote

      public CsvProcessor<T> withColumnQuote(char columnQuote)
      Quote character that is used to wrap each column. Alternative way to do setColumnQuote(char).

    • setLineTermination

      public void setLineTermination(String lineTermination)
      Sets the character which is written at the end of the row. Default is to use System.getProperty("line.separator");.

    • withLineTermination

      public CsvProcessor<T> withLineTermination(String lineTermination)
      Sets the character which is written at the end of the row. Default is to use System.getProperty("line.separator");. Alternative way to do setLineTermination(String).

    • setAllowPartialLines

      public void setAllowPartialLines(boolean allowPartialLines)
      Set to true to allow lines that do not have values for all of the columns. Otherwise an IllegalArgumentException is thrown.

    • withAllowPartialLines

      public CsvProcessor<T> withAllowPartialLines(boolean allowPartialLines)
      Set to true to allow lines that do not have values for all of the columns. Otherwise an IllegalArgumentException is thrown. Alternative way to do setAllowPartialLines(boolean).

    • setAlwaysTrimInput

      public void setAlwaysTrimInput(boolean alwaysTrimInput)
      Set to true to always call String.trim() on data input columns to remove any spaces from the start or end.

    • withAlwaysTrimInput

      public CsvProcessor<T> withAlwaysTrimInput(boolean alwaysTrimInput)
      Set to true to always call String.trim() on data input columns to remove any spaces from the start or end. Alternative way to do setAlwaysTrimInput(boolean).

    • setHeaderValidation

      public void setHeaderValidation(boolean headerValidation)
      Set to false to not validate the header when it is read in. Default is true.

    • withHeaderValidation

      public CsvProcessor<T> withHeaderValidation(boolean headerValidation)
      Set to false to not validate the header when it is read in. Default is true.

    • setFirstLineHeader

      public void setFirstLineHeader(boolean firstLineHeader)
      Set to false if the first line is a header line to be processed. Default is true.

    • withFirstLineHeader

      public CsvProcessor<T> withFirstLineHeader(boolean firstLineHeader)
      Set to false if the first line is a header line to be processed. Default is true.

    • setColumnNameMatcher

      public void setColumnNameMatcher(ColumnNameMatcher columnNameMatcher)
      Set the column name matcher class which will be used to see if the column from the CSV file matches the definition name. This can be used if you have optional suffix characters such as "*" or something. Default is String.equals(Object).

    • withColumnNameMatcher

      public CsvProcessor<T> withColumnNameMatcher(ColumnNameMatcher columnNameMatcher)
      Set the column name matcher class which will be used to see if the column from the CSV file matches the definition name. This can be used if you have optional suffix characters such as "*" or something. Default is String.equals(Object).

    • setFlexibleOrder

      public void setFlexibleOrder(boolean flexibleOrder)
      Set to true if the order of the input columns is flexible and does not have to match the order of the definition fields in the entity. The order is determined by the header columns so their must be a header. Default is false. WARNING: If you are using flexible ordering, this CsvProcessor cannot be used with multiple files at the same time since the column orders are dynamic depending on the input file being read.

    • withFlexibleOrder

      public CsvProcessor<T> withFlexibleOrder(boolean flexibleOrder)
      Set to true if the order of the input columns is flexible and does not have to match the order of the definition fields in the entity. The order is determined by the header columns so their must be a header. Default is false. WARNING: If you are using flexible ordering, this CsvProcessor cannot be used with multiple files at the same time since the column orders are dynamic depending on the input file being read.

    • setIgnoreUnknownColumns

      public void setIgnoreUnknownColumns(boolean ignoreUnknownColumns)
      Set to true to ignore columns that are not know to the configuration. Default is to raise an error. WARNING: If you are using unknown columns, this CsvProcessor cannot be used with multiple files at the same time since the column position is dynamic depending on the input file being read.

    • withIgnoreUnknownColumns

      public CsvProcessor<T> withIgnoreUnknownColumns(boolean ignoreUnknownColumns)
      Set to true to ignore columns that are not know to the configuration. Default is to raise an error. WARNING: If you are using unknown columns, this CsvProcessor cannot be used with multiple files at the same time since the column position is dynamic depending on the input file being read.

    • setRowValidator

      public void setRowValidator(RowValidator<T> rowValidator)
      Set the validator which will validate each entity after it has been parsed.

    • withAllowLineTerminationInColumns

      public CsvProcessor<T> withAllowLineTerminationInColumns(boolean allowLineTerminationInColumns)
      Set to true to allow line-termination characters inside of a column.

    • setAllowLineTerminationInColumns

      public void setAllowLineTerminationInColumns(boolean allowLineTerminationInColumns)
      Set to true to allow line-termination characters inside of a column.

    • withSuperClassColumnsFirst

      public CsvProcessor<T> withSuperClassColumnsFirst(boolean superClassColumnsFirst)
      Set to true to mean that the fields discovered in the superclass come _before_ the sub-classes. Default is false.

    • setSuperClassColumnsFirst

      public void setSuperClassColumnsFirst(boolean superClassColumnsFirst)
      Set to true to mean that the fields discovered in the superclass come _before_ the sub-classes. Default is false.

    • withRowValidator

      public CsvProcessor<T> withRowValidator(RowValidator<T> rowValidator)
      Set the validator which will validate each entity after it has been parsed.