Package io.github.dornol.excelkit.excel

Class ExcelReader<T>

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

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

Since:
2025-07-19

  • Constructor Details

    • ExcelReader

      public ExcelReader(Supplier<T> instanceSupplier, @Nullable jakarta.validation.Validator validator)
      Constructs an ExcelReader 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)

    • ExcelReader

      public ExcelReader(Supplier<T> instanceSupplier)
      Constructs an ExcelReader 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> ExcelReader<T> setter(Supplier<T> instanceSupplier)
      Creates an ExcelReader in setter mode. Symmetric with mapping(Function) and forMap() — all three read modes start with a static factory. 
      
 ExcelReader.setter(User::new)
     .column("Name", (u, cell) -> u.name = cell.asString())
     .build(inputStream)
     .read(result -> { ... });
      Type Parameters:
      T - The row data type
      Parameters:
      instanceSupplier - A supplier to create new instances of T for each row
      Returns:
      A new ExcelReader configured in setter mode
      Since:
      0.14.0

    • setter

      public static <T> ExcelReader<T> setter(Supplier<T> instanceSupplier, @Nullable jakarta.validation.Validator validator)
      Creates an ExcelReader 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 ExcelReader configured in setter mode
      Since:
      0.14.0

    • mapping

      public static <T> ExcelReader<T> mapping(Function<RowData,T> rowMapper)
      Creates an ExcelReader 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. Column definitions are not needed — access columns by header name or index within the mapping function. 

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

    • mapping

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

    • forMap

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

      The returned reader exposes the standard fluent API (sheetIndex(int), 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. 

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

    • forMap

      public static ExcelReader<Map<String,String>> forMap(String... columnNames)
      Creates a reader that parses Excel files into Map<String, String> rows, including only the specified columns. Columns not listed are ignored. 
      
 ExcelReader.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 ExcelReader in map mode with column filtering
      Since:
      0.14.0

    • sheetIndex

      public ExcelReader<T> sheetIndex(int sheetIndex)
      Sets the zero-based sheet index to read from. Defaults to 0 (the first sheet).
      Parameters:
      sheetIndex - The zero-based index of the sheet to read
      Returns:
      This ExcelReader instance for chaining

    • headerRowIndex

      public ExcelReader<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 ExcelReader instance for chaining

    • password

      public ExcelReader<T> password(String password)
      Sets the password for reading encrypted Excel files.

      If the file is encrypted with the "agile" encryption mode (as produced by ExcelWriter.password(String)), this password will be used to decrypt it before parsing.

      Parameters:
      password - the file password
      Returns:
      this reader for chaining
      Since:
      0.14.0

    • column

      public ExcelReader<T> column(BiConsumer<T,CellData> setter)
      Registers a positional column mapping. Columns are matched to the spreadsheet 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 ExcelReader<T> column(String headerName, BiConsumer<T,CellData> setter)
      Registers a name-based column mapping. The column is matched to the spreadsheet column whose header cell equals headerName in the header row.
      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 ExcelReader<T> columnAt(int columnIndex, BiConsumer<T,CellData> setter)
      Registers an index-based column mapping. The column is matched to the spreadsheet column at the given 0-based index, regardless of header or registration order.
      Parameters:
      columnIndex - 0-based column index in the Excel file
      setter - a BiConsumer that writes a cell value into the row object
      Returns:
      this reader for chaining

    • required

      public ExcelReader<T> required()
      Marks the last registered column as required.

      A required column will produce a validation error if its cell value is blank or empty. 

      
 ExcelReader.setter(Person::new)
     .column("Name", (p, c) -> p.setName(c.asString())).required()
     .column("Age", (p, c) -> p.setAge(c.asInt()))
     .build(inputStream)
     .read(result -> { ... });
      Returns:
      this reader for chaining
      Throws:
      IllegalStateException - if no columns have been registered

    • skipColumn

      public ExcelReader<T> skipColumn()
      Skips one column during reading by registering a no-op mapping at the next positional slot.
      Returns:
      this reader for chaining

    • skipColumns

      public ExcelReader<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 ExcelReader<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 ExcelReader instance for chaining

    • build

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

    • getSheetNames

      public static List<ExcelSheetInfo> getSheetNames(InputStream inputStream)
      Returns the list of sheet names and indices from an Excel file.
      Parameters:
      inputStream - The input stream of the Excel file (will be consumed)
      Returns:
      A list of ExcelSheetInfo records containing sheet names and indices

    • getSheetHeaders

      public static List<String> getSheetHeaders(InputStream inputStream, int sheetIndex, int headerRowIndex)
      Returns the header names from a specific sheet.
      Parameters:
      inputStream - The input stream of the Excel file (will be consumed)
      sheetIndex - The 0-based sheet index
      headerRowIndex - The 0-based header row index
      Returns:
      A list of header names