Package io.github.dornol.excelkit.excel

Class ExcelReadHandler<T>

java.lang.Object
io.github.dornol.excelkit.core.TempResourceContainer
io.github.dornol.excelkit.core.AbstractReadHandler<T>
io.github.dornol.excelkit.excel.ExcelReadHandler<T>
Type Parameters:
T - The target row data type to map each row into
All Implemented Interfaces:
AutoCloseable
public class ExcelReadHandler<T> extends AbstractReadHandler<T>
Reads Excel (.xlsx) files using Apache POI's event-based streaming API.

This handler parses sheet data row by row, maps values to Java objects, and performs optional validation. It is optimized for large files and avoids loading the entire workbook into memory.

Resource management

On construction, the handler copies the input stream to a temporary file on disk so that the underlying POI API can read it. These temp resources (and, if applicable, the decrypted copy of an encrypted file) are released when:
  • read(Consumer) / AbstractReadHandler.readStrict(Consumer) returns or throws — cleanup is automatic.
  • The stream returned by readAsStream() is closed — always use try-with-resources, since this stream also holds a background producer thread: 
    
 try (Stream<ReadResult<T>> stream = handler.readAsStream()) {
     stream.forEach(result -> ...);
 }
    Abandoning the stream without closing it leaks the temp file until the JVM exits (the producer thread is a daemon and will eventually self-terminate).

Large file tuning

For large or complex Excel files, you may need to adjust POI's internal limits via ExcelKitConfig.configureLargeFileSupport() before reading. This adjusts:
  • ZipSecureFile.setMaxFileCount — maximum number of internal zip entries
  • IOUtils.setByteArrayMaxOverride — maximum in-memory byte array size
Since:
2025-07-19

  • Method Details

    • read

      public void read(Consumer<ReadResult<T>> consumer)
      Starts parsing the Excel file and invokes the given consumer for each row result.

      Each row is converted into a target object via the configured column setters. Validation (if enabled) is performed after mapping.

      Specified by:
      read in class AbstractReadHandler<T>
      Parameters:
      consumer - Callback to receive parsed and validated row results

    • readAsStream

      public Stream<ReadResult<T>> readAsStream()
      Reads the file as a stream of row results using a background producer thread.

      Important: The returned stream holds file and thread resources. Always use try-with-resources to ensure proper cleanup: 

      
 try (Stream<ReadResult<T>> stream = handler.readAsStream()) {
     stream.forEach(result -> ...);
 }
      Specified by:
      readAsStream in class AbstractReadHandler<T>
      Returns:
      A stream of parsed and validated row results