Package io.github.dornol.excelkit.excel

Class ExcelHandler

java.lang.Object
io.github.dornol.excelkit.excel.ExcelHandler
All Implemented Interfaces:
FileHandler
public final class ExcelHandler extends Object implements FileHandler
Handles the final output stage of an Excel export.

This class is responsible for writing the SXSSFWorkbook to an OutputStream, with optional support for Excel password encryption. It ensures that the workbook is consumed only once.

Why not AutoCloseable? The primary usage pattern is ResponseEntity<StreamingResponseBody>, where the handler is captured by a lambda and consumed asynchronously. Implementing AutoCloseable would cause IDE "resource not closed" warnings in this pattern, requiring @SuppressWarnings("resource") on every call site.

The workbook is always closed inside writeTo(OutputStream) overloads, and there is no realistic code path where the handler is obtained but never consumed, since callers either invoke it immediately or pass it to a StreamingResponseBody lambda.

Since:
2025-07-19

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    writeTo(OutputStream outputStream)
    Writes the workbook to the given OutputStream.
    void
    writeTo(OutputStream outputStream, char[] password)
    Writes the workbook to the given OutputStream with Excel-compatible password encryption.
    void
    writeTo(OutputStream outputStream, String password)
    Writes the workbook to the given OutputStream with Excel-compatible password encryption.
    void
    writeTo(Path path, char[] password)
    Writes the workbook directly to a file path with Excel-compatible password encryption.
    void
    writeTo(Path path, String password)
    Writes the workbook directly to a file path with Excel-compatible password encryption.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface io.github.dornol.excelkit.core.FileHandler

    writeTo

  • Method Details

    • writeTo

      public void writeTo(OutputStream outputStream)
      Writes the workbook to the given OutputStream.

      If a password was set via ExcelWriter.password(String) or ExcelWorkbook.password(String), the output is automatically encrypted using the "agile" encryption mode.

      This method can only be called once; subsequent calls will throw an exception.

      Specified by:
      writeTo in interface FileHandler
      Parameters:
      outputStream - The OutputStream to write the Excel file to
      Throws:
      ExcelWriteException - If this method has already been called or if an I/O error occurs

    • writeTo

      public void writeTo(OutputStream outputStream, String password)
      Writes the workbook to the given OutputStream with Excel-compatible password encryption.

      This overload encrypts the file using the "agile" encryption mode supported by modern Excel versions. Cannot be used when a password was already set via ExcelWriter.password(String) or ExcelWorkbook.password(String) — use writeTo(OutputStream) instead.

      Memory note: POI's encryption API does not support file-backed buffering for the OLE container — the encrypted payload is held in heap (≈ size of the resulting XLSX) before being streamed out. For very large exports (hundreds of MB) plan heap accordingly, or prefer the plain writeTo(OutputStream) path.

      Parameters:
      outputStream - The OutputStream to write the encrypted Excel file to
      password - The password to protect the Excel file with
      Throws:
      ExcelWriteException - If an I/O or encryption error occurs during writing
      IllegalStateException - If a password was already set at the writer level, or if already consumed
      Since:
      0.16.5

    • writeTo

      public void writeTo(OutputStream outputStream, char[] password)
      Writes the workbook to the given OutputStream with Excel-compatible password encryption.

      This overload accepts a char[] to allow callers to clear the password from memory after use. The array is zeroed out after encryption completes (or on failure). Cannot be used when a password was already set via ExcelWriter.password(String) or ExcelWorkbook.password(String) — use writeTo(OutputStream) instead.

      Memory note: same as writeTo(OutputStream, String) — POI buffers the encrypted OLE container in heap.

      Parameters:
      outputStream - The OutputStream to write the encrypted Excel file to
      password - The password as a char array (will be zeroed after use)
      Throws:
      ExcelWriteException - If an I/O or encryption error occurs during writing
      IllegalStateException - If a password was already set at the writer level, or if already consumed
      Since:
      0.16.5

    • writeTo

      public void writeTo(Path path, String password)
      Writes the workbook directly to a file path with Excel-compatible password encryption.

      Convenience overload that opens a buffered OutputStream to the given path and delegates to writeTo(OutputStream, String). Cannot be used when a password was already set via ExcelWriter.password(String) or ExcelWorkbook.password(String) — use FileHandler.writeTo(Path) instead.

      Parameters:
      path - The destination file path
      password - The password to protect the Excel file with
      Throws:
      ExcelWriteException - If an I/O or encryption error occurs during writing
      IllegalStateException - If a password was already set at the writer level, or if already consumed
      Since:
      0.16.6

    • writeTo

      public void writeTo(Path path, char[] password)
      Writes the workbook directly to a file path with Excel-compatible password encryption.

      This overload accepts a char[] to allow callers to clear the password from memory after use. The array is zeroed out after encryption completes (or on failure). Cannot be used when a password was already set via ExcelWriter.password(String) or ExcelWorkbook.password(String) — use FileHandler.writeTo(Path) instead.

      Parameters:
      path - The destination file path
      password - The password as a char array (will be zeroed after use)
      Throws:
      ExcelWriteException - If an I/O or encryption error occurs during writing
      IllegalStateException - If a password was already set at the writer level, or if already consumed
      Since:
      0.16.6