Package io.github.dornol.excelkit.csv

Class CsvReader<T>

java.lang.Object
io.github.dornol.excelkit.csv.CsvReader<T>
Type Parameters:
T - The type of the object that represents one CSV row
public class CsvReader<T> extends Object
Builder-style class for configuring CSV row readers.

CsvReader allows you to define how each CSV cell maps to your target object T, and optionally integrates Bean Validation support. Once configuration is complete, use build(InputStream) to create a CsvReadHandler.

Since:
2025-07-19

  • Constructor Details

    • CsvReader

      public CsvReader(Supplier<T> instanceSupplier, @Nullable jakarta.validation.Validator validator)
      Constructs a CsvReader in setter mode with instance supplier and optional validator.
      Parameters:
      instanceSupplier - A supplier to create new instances of T for each row
      validator - Optional Bean Validation validator (nullable)

    • CsvReader

      public CsvReader(Supplier<T> instanceSupplier)
      Constructs a CsvReader in setter mode without Bean Validation.
      Parameters:
      instanceSupplier - A supplier to create new instances of T for each row

  • Method Details

    • setter

      public static <T> CsvReader<T> setter(Supplier<T> instanceSupplier)
      Creates a CsvReader in setter mode. Symmetric with mapping(Function) and forMap().
      Type Parameters:
      T - The row data type
      Parameters:
      instanceSupplier - A supplier to create new instances of T for each row
      Returns:
      A new CsvReader configured in setter mode
      Since:
      0.14.0

    • setter

      public static <T> CsvReader<T> setter(Supplier<T> instanceSupplier, @Nullable jakarta.validation.Validator validator)
      Creates a CsvReader in setter mode with Bean Validation.
      Type Parameters:
      T - The row data type
      Parameters:
      instanceSupplier - A supplier to create new instances of T for each row
      validator - Bean Validation validator
      Returns:
      A new CsvReader configured in setter mode
      Since:
      0.14.0

    • mapping

      public static <T> CsvReader<T> mapping(Function<RowData,T> rowMapper)
      Creates a CsvReader in mapping mode for immutable object construction.

      In this mode, each row is passed as a RowData to the mapping function, which creates the target object in a single step. 

      
 CsvReader.mapping(row -> new PersonRecord(
         row.get("Name").asString(),
         row.get("Age").asInt()
 )).build(inputStream).read(result -> { ... });
      Type Parameters:
      T - The type of the object that represents one CSV row
      Parameters:
      rowMapper - A function that creates an instance of T from a RowData
      Returns:
      A new CsvReader configured in mapping mode

    • mapping

      public static <T> CsvReader<T> mapping(Function<RowData,T> rowMapper, @Nullable jakarta.validation.Validator validator)
      Creates a CsvReader in mapping mode with Bean Validation support.
      Type Parameters:
      T - The type of the object that represents one CSV row
      Parameters:
      rowMapper - A function that creates an instance of T from a RowData
      validator - Optional Bean Validation validator (nullable)
      Returns:
      A new CsvReader configured in mapping mode
      See Also:

    • forMap

      public static CsvReader<Map<String,String>> forMap()
      Creates a reader that parses CSV files into Map<String, String> rows by auto-discovering columns from the header row.

      The returned reader exposes the standard fluent API (dialect(CsvDialect), delimiter(char), charset(Charset), headerRowIndex(int), onProgress(int, ProgressCallback)) but rejects column(BiConsumer), column(String, BiConsumer), columnAt(int, BiConsumer), skipColumn(), and skipColumns(int) at runtime — map mode infers columns automatically from the header row and does not use the setter API. 

      
 CsvReader.forMap()
     .dialect(CsvDialect.EXCEL)
     .build(inputStream)
     .read(result -> {
         Map<String, String> row = result.data();
         String name = row.get("Name");
     });
      Returns:
      a new CsvReader in map mode
      Since:
      0.12.0

    • forMap

      public static CsvReader<Map<String,String>> forMap(String... columnNames)
      Creates a reader that parses CSV files into Map<String, String> rows, including only the specified columns. Columns not listed are ignored. 
      
 CsvReader.forMap("Name", "Age")
     .build(inputStream)
     .read(result -> {
         // result.data() contains only "Name" and "Age" keys
     });
      Parameters:
      columnNames - the header names to include (others are filtered out)
      Returns:
      a new CsvReader in map mode with column filtering
      Since:
      0.14.0

    • dialect

      public CsvReader<T> dialect(CsvDialect dialect)
      Applies a predefined CSV dialect configuration.

      Sets the delimiter and charset in one call. Individual settings can be overridden after calling this method.

      Parameters:
      dialect - the dialect to apply
      Returns:
      This CsvReader instance for chaining
      Since:
      0.9.2

    • headerRowIndex

      public CsvReader<T> headerRowIndex(int headerRowIndex)
      Sets the zero-based row index of the header row. Rows before this index will be skipped during reading. Defaults to 0 (the first row).
      Parameters:
      headerRowIndex - The zero-based index of the header row
      Returns:
      This CsvReader instance for chaining

    • delimiter

      public CsvReader<T> delimiter(char delimiter)
      Sets the delimiter character used to separate fields. Defaults to comma (',').
      Parameters:
      delimiter - The delimiter character
      Returns:
      This CsvReader instance for chaining

    • charset

      public CsvReader<T> charset(Charset charset)
      Sets the character encoding for reading the CSV file. Defaults to StandardCharsets.UTF_8.
      Parameters:
      charset - The charset to use
      Returns:
      This CsvReader instance for chaining

    • column

      public CsvReader<T> column(BiConsumer<T,CellData> setter)
      Registers a positional column mapping. Columns are matched to the CSV in the order they are registered (after headerRowIndex(int) is accounted for).
      Parameters:
      setter - a BiConsumer that writes a cell value into the row object
      Returns:
      this reader for chaining

    • column

      public CsvReader<T> column(String headerName, BiConsumer<T,CellData> setter)
      Registers a name-based column mapping. The column is matched to the CSV column whose header equals headerName.
      Parameters:
      headerName - the header name to match
      setter - a BiConsumer that writes a cell value into the row object
      Returns:
      this reader for chaining

    • columnAt

      public CsvReader<T> columnAt(int columnIndex, BiConsumer<T,CellData> setter)
      Registers an index-based column mapping. The column is matched to the CSV column at the given 0-based index.
      Parameters:
      columnIndex - 0-based column index
      setter - a BiConsumer that writes a cell value into the row object
      Returns:
      this reader for chaining

    • required

      public CsvReader<T> required()
      Marks the last registered column as required. A required column produces a validation error if its cell value is blank or empty.
      Returns:
      this reader for chaining
      Throws:
      IllegalStateException - if no columns have been registered

    • skipColumn

      public CsvReader<T> skipColumn()
      Skips one column during reading by registering a no-op mapping.
      Returns:
      this reader for chaining

    • skipColumns

      public CsvReader<T> skipColumns(int count)
      Skips the specified number of positional columns.
      Parameters:
      count - the number of columns to skip (must be non-negative)
      Returns:
      this reader for chaining
      Throws:
      IllegalArgumentException - if count is negative

    • onProgress

      public CsvReader<T> onProgress(int interval, ProgressCallback callback)
      Registers a progress callback that fires every interval rows during reading.
      Parameters:
      interval - the number of rows between each callback invocation (must be positive)
      callback - the callback to invoke
      Returns:
      This CsvReader instance for chaining

    • build

      public CsvReadHandler<T> build(InputStream inputStream)
      Finalizes the configuration and builds a CsvReadHandler for parsing the given CSV stream.
      Parameters:
      inputStream - The input stream of the CSV file
      Returns:
      A handler to execute CSV parsing