Package io.keikai.axyra.sheets.io

Class StreamWorkbook

java.lang.Object
io.keikai.axyra.sheets.io.StreamWorkbook
All Implemented Interfaces:
AutoCloseable
public final class StreamWorkbook extends Object implements AutoCloseable
Writes an XLSX file row by row, in memory that does not grow with the row count.

Use this when authoring a large export. The ordinary Workbook path builds the whole workbook in memory before writing a byte, which is the right trade when you need to read, edit, recalculate or lay out — and the wrong one when you are pouring a result set into a file. Each row here is serialized and deflated as it arrives; the engine holds one row at a time. Writing 1,000,000 rows of five columns costs the same memory as writing ten.

What you give up, in exchange:

  • Rows go out in ascending order and never come back. Writing row 5 after row 9 throws — a streaming writer cannot rewind the file.
  • Values only — cell values, number formats, bold / italic. No charts, images, merges, conditional formats, comments or validation; those need the whole-workbook model. Reach for Workbook when you need them.
  • No recalculation. Formulas are written verbatim; supply the cached value with StreamRow.setFormula(int, String, double, int) if the consumer must see a number before opening in Excel.
  • Text is stored inline rather than in a shared string table, so heavily repeating text yields a larger file than the modeled writer produces. The table is what a streaming writer cannot afford: it must stay resident until the last sheet closes.

The file is complete only after close() (or finish()); abandoning the writer leaves a partial file behind, so use try-with-resources: 


 try (StreamWorkbook wb = StreamWorkbook.create(Path.of("report.xlsx"))) {
     int header = wb.addStyle(StreamStyle.defaults().withBold());
     int money  = wb.addStyle(StreamStyle.defaults().withNumberFormat("#,##0.00"));
     wb.startSheet("Sales");
     wb.row(0).addText("Customer", header).addText("Amount", header).commit();
     int r = 1;
     for (Order o : orders) {
         wb.row(r++).addText(o.customer()).addNumber(o.amount(), money).commit();
     }
 }

Not thread-safe: rows are ordered, so one writer belongs to one thread.

  • Method Details

    • create

      public static StreamWorkbook create(Path file)
      Opens a streaming writer on file, replacing it if it exists.

      Under license enforcement this counts as a file operation and the output is stamped as evaluation material, exactly as an ordinary save is.

    • addStyle

      public int addStyle(StreamStyle style)
      Registers a style and returns the index cells reference. Identical styles return the same index, so calling this per row is free.

    • startSheet

      public void startSheet(String name)
      Closes any open sheet and starts a new one. Sheet names follow Excel's rules (31 characters, none of []:*?/\); the engine writes what it is given.

    • row

      public StreamRow row(int index)
      Begins row index (0-based). The returned builder is reused across rows — fill it and call StreamRow.commit() before asking for the next row.

    • finish

      public void finish()
      Completes the package and closes the file. Called automatically by close(); call it directly only to surface a write failure at a specific point.

    • close

      public void close()
      Finishes the workbook if it has not been finished already, so a normal try-with-resources exit produces a complete file.

      If the block exits by exception, finish may itself throw (for instance with no sheet ever started). The native writer is released in either case, so no handle leaks.

      Specified by:
      close in interface AutoCloseable

    • isFinished

      public boolean isFinished()
      Whether the package has been completed.