Hypaxel for Java
Large Excel files in Java without the heap growth: stream XLSX from records to any OutputStream or Spring response, and read workbooks row by row.
v0.3.0 unreleasedLast updated View as Markdown
Large Excel exports on the JVM often mean gigabytes of short-lived garbage per file, or a sliding window of rows held in memory. Hypaxel for Java writes .xlsx files as a forward-only stream: each cell is serialized to UTF-8 XML the moment you write it and compressed straight into a small buffer, so memory stays flat whether you export 10 rows or a million, and a download can start while your query is still running. A workbook allocates its buffers once (about 0.17 MB in total), no matter how many rows follow. It reads workbooks the same way: one row at a time, with memory bounded by the shared string table plus one row, about 4 times faster than the FastExcel reader. It is pure Java with only java.base as a dependency, no JNI and no native library, and it reads naturally from Java, Kotlin and Scala.
- Package
- de.vensas:hypaxel
- Requires
- Java 17+
- Engine
- Native Java, java.base only; writer and streaming reader
- Web
- Any OutputStream: Servlet, Spring StreamingResponseBody
- Registry
- Maven Central (not published yet)
- License
- Apache-2.0
Install#
<dependency>
<groupId>de.vensas</groupId>
<artifactId>hypaxel</artifactId>
<version>0.3.0</version>
</dependency>Not published yetde.vensas:hypaxel is not on Maven Central yet. The command above is what installation will look like once it is.
The artifact is not published yet. Until then, build it from source: see Building from source. The coordinates will be:
<dependency>
<groupId>de.vensas</groupId>
<artifactId>hypaxel</artifactId>
<version>0.3.0</version>
</dependency>implementation("de.vensas:hypaxel:0.3.0")Requires Java 17 or later. The library is a Java module (de.vensas.hypaxel) that also works on the class path.
Quick start#
import de.vensas.hypaxel.*;
public record Order(
@ExcelColumn(name = "Order #", order = 0, width = 10) int id,
String customer,
@ExcelColumn(format = "#,##0.00") BigDecimal amount,
@ExcelColumn(format = "yyyy-mm-dd") LocalDate created,
@ExcelIgnore String internalNote) {
}
try (XlsxWriter writer = XlsxWriter.create(Path.of("orders.xlsx"))) {
writer.writeWorksheet("Orders", Order.class, orders);
}writeWorksheet adds a worksheet with a styled, frozen header row, an auto filter and column widths. orders is any Iterable or Stream, so rows can come straight from a database cursor.
Cell by cell, with the typed write overloads (no boxing, nothing allocated per cell):
try (XlsxWriter writer = XlsxWriter.create(out)) {
Worksheet sheet = writer.addWorksheet("Orders");
for (Order order : orders) {
sheet.write(order.id()).write(order.customer()).write(order.amount()).write(order.created());
sheet.endRow();
}
}Reading#
XlsxReader reads workbooks the same way they are written: one row at a time, with memory bounded by the shared string table plus the current row.
try (XlsxReader reader = XlsxReader.open(Path.of("orders.xlsx"))) {
System.out.println(reader.sheetNames());
try (SheetReader rows = reader.worksheet("Orders")) { // or worksheet(0)
for (Row row = rows.nextRow(); row != null; row = rows.nextRow()) {
// row.number() is the 1-based Excel row; rows without values are skipped.
String customer = row.getString(1); // 1-based columns
double amount = row.getNumber(3); // NaN if not a number
LocalDateTime created = row.getLocalDateTime(4); // null if not a date
switch (row.type(5)) {
case STRING -> System.out.println(row.getString(5));
case NUMBER, DATE_TIME -> System.out.println(row.getNumber(5));
case BOOLEAN -> System.out.println(row.getBoolean(5));
case ERROR -> System.out.println(row.getError(5)); // "#N/A", ...
case EMPTY -> { }
}
}
}
}XlsxReader.open takes a Path, a SeekableByteChannel, a byte[] or an InputStream. The XLSX directory sits at the end of the file, so an InputStream is read into memory first; use a Path for large files. Closing the reader closes the file or channel.
The same stream also comes as an Iterable, as dense lists and as a Stream:
for (Row row : reader.worksheet(0)) { ... } // Iterable; the Row is reused
List<Value> dense = row.values(); // columns 1..lastColumn(), Value.EMPTY for gaps
List<Object> objects = row.toList(); // String, Double, Boolean, LocalDateTime, ..., null for gaps
for (CellValue cell : row.cells()) { cell.column(); cell.value(); }
try (Stream<Row> rows = reader.worksheet("Orders").stream()) { // independent copies
List<List<Object>> table = rows.map(Row::toList).toList();
}SheetReader.nextRow() and its iterator reuse one Row, which is valid until the next row is read. Keep row.copy(), row.toList() or the values you need. stream() yields copies, so they may be collected.
XlsxReader
| Method | Purpose |
|---|---|
open(Path | SeekableByteChannel | byte[] | InputStream, ReadOptions?) | Reads the package structure, sheet list and cell formats |
sheets(), sheetNames() | Sheets in workbook order: name, SheetVisibility (VISIBLE, HIDDEN, VERY_HIDDEN), SheetKind (WORKSHEET, CHARTSHEET, OTHER) |
worksheet(name) | Sheet by name: exact match first, then ignoring case |
worksheet(index) | Sheet by 0-based position |
isDate1904() | Whether the workbook uses the 1904 date system |
sharedStringCount() | Entries in the shared string table (loads it) |
Row
| Method | Purpose |
|---|---|
number(), cellCount(), lastColumn(), column(i) | Row number, cells with a value and their columns |
type(column) | CellType: EMPTY, STRING, NUMBER, BOOLEAN, DATE_TIME, ERROR |
getString, getNumber, getBoolean, getError | Typed values without allocation (except the String of inline text) |
getDateTime(column) | ExcelDateTime: serial(), kind(), toLocalDateTime(), toLocalDate(), toLocalTime(), toDuration(), toObject() |
getLocalDateTime(column) | Shortcut for getDateTime(column).toLocalDateTime() |
getValue(column), getObject(column), getText(column) | Value as Value, as a plain Java object, or as text like Excel’s General format |
sharedStringIndex(column) | Index in the shared string table, to convert repeated text once |
cells(), values(), toList(), copy() | Cells with values, dense values, dense objects, a detached copy |
Values#
Text (shared strings, inline strings, cached formula results), numbers, booleans, errors and dates. A number whose built-in or custom number format shows a date, time or duration becomes DATE_TIME with a DateKind (DATE, DATE_TIME, TIME, DURATION); the raw serial stays available. toObject() gives a LocalDateTime, a LocalTime for times below one day, or a Duration. Both date systems are supported, including Excel’s fictitious 1900-02-29 (serial 60, which converts to null). Times are rounded to the millisecond. Formulas yield their cached result; a formula that was never calculated has no value.
Files from Excel, LibreOffice, Apache POI, openpyxl and other producers are read: package relationships instead of fixed paths, Strict Open XML, prefixed namespaces, cells and rows without references, out-of-order cells, rich text, phonetic runs, inline strings, CDATA, ISO 8601 dates (t="d") and Excel’s _xHHHH_ escapes.
Not read (yet): formula text, styles beyond date detection, merged ranges, comments, hyperlinks and other drawing or table parts.
Memory and threads#
Worksheets are decompressed and parsed as a stream. What stays in memory is the shared string table (text that a workbook stores once) plus the current row. Reading the 1M-row benchmark file completes with -Xmx16m when its text is inline and with -Xmx96m when its 1M distinct strings are in the shared table.
One XlsxReader can open several worksheets at once, also from different threads; they share the parsed workbook and the shared string table. Each SheetReader is used by one thread at a time.
Errors and untrusted files#
- Document type declarations are rejected, so there is no entity expansion and no external entities.
- Every XML token (16 MiB) and row (16,384 cells, 256 MiB of text) is bounded, and ZIP entries must match their declared size and CRC-32.
ReadOptions.builder().maxSharedStringsBytes(...)caps the shared string table (1 GiB by default).- Legacy
.xlsfiles, encrypted workbooks, CSV and Word files fail with anXlsxExceptionof kindINVALID_FILE. Damaged parts fail withMALFORMEDand apart()such asxl/worksheets/sheet1.xml; messages name the part and row. - Invalid UTF-8 in text is replaced with U+FFFD.
Streaming HTTP responses#
The core artifact has no web dependencies; a response body is just an OutputStream. XlsxWriter.CONTENT_TYPE is the XLSX media type. Output reaches the client in chunks while rows are written, and closing the writer completes the file.
Servlet (Jakarta or javax)#
@Override
protected void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
response.setContentType(XlsxWriter.CONTENT_TYPE);
response.setHeader("Content-Disposition", "attachment; filename=\"orders.xlsx\"");
try (XlsxWriter writer = XlsxWriter.create(response.getOutputStream());
Stream<Order> orders = repository.streamAll()) {
writer.writeWorksheet("Orders", Order.class, orders);
}
}Spring MVC#
@GetMapping("/orders.xlsx")
public ResponseEntity<StreamingResponseBody> orders() {
StreamingResponseBody body = out -> {
try (XlsxWriter writer = XlsxWriter.create(out);
Stream<Order> orders = repository.streamAll()) {
writer.writeWorksheet("Orders", Order.class, orders);
}
};
return ResponseEntity.ok()
.contentType(MediaType.parseMediaType(XlsxWriter.CONTENT_TYPE))
.header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"orders.xlsx\"")
.body(body);
}A Stream backed by a database cursor needs an open transaction for as long as it is read; with Spring Data, read it inside a read-only TransactionTemplate in the StreamingResponseBody.
When an export fails half-way#
Closing the writer completes the workbook, also when try-with-resources closes it because of an exception. The client would then receive a valid file that is missing rows. Call abort() so that the download is truncated and Excel rejects it:
XlsxWriter writer = XlsxWriter.create(response.getOutputStream());
try {
writer.writeWorksheet("Orders", Order.class, orders);
writer.close();
} catch (RuntimeException | IOException e) {
writer.abort();
throw e;
}When the destination itself fails (the client disconnects), the writer aborts on its own and the IOException propagates.
Object mapping#
Columns are the record components of a record, or the properties of a class: its fields, in declaration order (superclasses first), that have a public accessor named getX, isX or x, followed by getters without a field. That covers records, JavaBeans, Kotlin data classes and Scala case classes.
| Annotation | Purpose |
|---|---|
@ExcelColumn(name = "Order #") | Header text; defaults to the property name |
@ExcelColumn(order = 0) | Sort key; columns without one keep declaration order, after ordered ones |
@ExcelColumn(format = "#,##0.00") | Excel number format for the column’s cells |
@ExcelColumn(width = 30) | Column width in characters; estimated from header and type when 0 |
@ExcelIgnore | Leaves the property out |
Annotations go on the record component, the field or the getter.
writer.writeWorksheet("Orders", Order.class, orders); // new sheet: header, frozen row, filter, widths
Worksheet sheet = writer.addWorksheet("Report");
sheet.addRow("Orders of May");
sheet.writeObjects(Order.class, orders, // append to a sheet you set up yourself
ObjectOptions.builder().autoFilter(true).build());Reflection runs once per type; rows are written through cached MethodHandles, and primitive properties are never boxed. Property types are written like the typed write overloads; enums are written by name and any other type through toString(). The mapped type must be accessible: public in an exported package, or in a package opened to the module de.vensas.hypaxel. On the class path every type works.
Kotlin and Scala#
The API is plain Java, so it needs no adapters:
data class Order(@field:ExcelColumn(name = "Order #") val id: Int, val customer: String, val amount: BigDecimal)
XlsxWriter.create(out).use { writer ->
writer.writeWorksheet("Orders", Order::class.java, orders)
}case class Order(id: Int, customer: String, amount: java.math.BigDecimal)
Using.resource(XlsxWriter.create(out)) { writer =>
writer.writeWorksheet("Orders", classOf[Order], orders.asJava)
}Full control with XlsxWriter#
try (XlsxWriter writer = XlsxWriter.create(Path.of("report.xlsx"))) {
StyleId header = writer.addStyle(Style.builder()
.bold().fontColor(Color.WHITE).fill(Color.hex("#305496")).align(HorizontalAlignment.CENTER).build());
StyleId money = writer.addStyle(Style.builder().numberFormat(NumberFormats.THOUSANDS2).build());
Worksheet sheet = writer.addWorksheet("Sales",
SheetOptions.builder().freezeRows(1).columnWidths(20, 12, 14).build());
sheet.addStyledRow(header, "Product", "Date", "Revenue");
sheet.write("Widget").write(LocalDate.of(2024, 5, 1)).write(1234.5, money).endRow();
sheet.write("Gadget").write(LocalDate.of(2024, 5, 2)).write(99.99, money).endRow();
sheet.write("Total").skipCells(1).writeFormula("SUM(C2:C3)", money).endRow();
}Worksheets are written one at a time: adding a worksheet completes the previous one. Rows go top to bottom and cells left to right. Merges, filters and tables can be added at any time before the worksheet completes.
In rows passed as objects, Cell.styled(value, style), Cell.formula("SUM(A1:A9)") and Cell.blank(style) give a single cell its own style or make it a formula. CellReference.of(row, column) and CellReference.range(...) build A1 references for formulas.
Styles are immutable values built with Style.builder(): font (fontName, fontSize, bold, italic, underline, strikethrough, fontColor), fill, border (Border.all(...) or Border.builder(), 13 line styles), alignment (align, verticalAlign, wrapText, indent, rotation) and numberFormat. NumberFormats has common format codes.
The full method tables for XlsxWriter and Worksheet are in the API reference.
Errors. Misuse and format limits throw the unchecked XlsxException, whose kind() tells them apart (TEXT_TOO_LONG, DUPLICATE_SHEET_NAME, …). A rejected cell writes nothing, so the workbook stays valid. The write methods only fill a buffer; the methods that end rows hand output to the destination and declare IOException.
Tables, row grouping and auto-fit#
Auto-fit columns#
Worksheet sheet = writer.addWorksheet("Orders", SheetOptions.builder().freezeRows(1).autoFitColumns().build());
// Or tune the sample and cap the width (in characters):
SheetOptions.builder().autoFit(AutoFit.builder().sampleRows(500).maxWidth(60).build()).build();Column widths come before the cell data in the file, so the writer holds back the worksheet’s XML while it measures the first sampleRows rows (1,000 by default). It then writes the widths and streams the rest as usual. Memory is bounded by the sample: at most sampleRows rows or 8 MiB of XML, whichever comes first. Rows after the sample are not measured.
Widths are estimated from the text, the number format (dates, #,##0.00, percentages, …) and the font size and weight of each cell. Formulas and blank cells are not measured. Widths you set with columnWidths or column always win. Without auto-fit, writing a cell costs nothing extra.
Excel tables#
addTable turns a range into an Excel table (a ListObject), with a header row, filter buttons, banded rows and a name you can use in formulas such as =SUM(Orders[Units]):
Worksheet sheet = writer.addWorksheet("Orders");
sheet.addRow("Product", "Units");
sheet.addRow("Widget", 3);
sheet.addRow("Gadget", 5);
sheet.addTable(ExcelTable.builder(1, 1, sheet.rowNumber(), 2)
.name("Orders") // optional: Table1, Table2, ... otherwise
.columns("Product", "Units") // must match the header row
.style(TableStyle.medium(9)) // light(1-21), medium(1-28), dark(1-11) or NONE
.build());With a header row (the default), columns must list the header texts exactly as written, because Excel identifies table columns by those names. headerRow(false) makes a table without one, whose columns are named Column1, Column2, … unless you name them. Table names are unique in the workbook, ignoring case, and follow Excel’s name rules. Tables cannot overlap each other, merged cells or the worksheet auto filter; violations throw an XlsxException. The range may include rows you have not written yet.
Row grouping#
Declare the deepest level when you add the worksheet, because Excel reads it before the rows:
Worksheet sheet = writer.addWorksheet("Regions", SheetOptions.builder()
.rowOutlineLevels(1) // deepest level used, 0-7
.outlineSummaryAbove() // the group's button sits on the row above it
.build());
sheet.addRow("North", 300);
sheet.beginRow(RowOptions.builder().outlineLevel(1).build()).addRow("Store A", 120); // addRow fills the begun row
sheet.beginRow(RowOptions.builder().outlineLevel(1).hidden().build()) // a collapsed group's rows are hidden
.write("Store B").write(180).endRow();RowOptions also sets height, style and collapsed (on the summary row of a collapsed group). A row started with beginRow that has no cells yet is filled by the next addRow, addRows, writeRows or writeObjects; once it has cells, those start a new row as before.
Options#
XlsxOptions.builder():
| Option | Default | Meaning |
|---|---|---|
compressionLevel | 1 | Deflate level 0-9. Level 6 gives smaller files for more CPU time |
stringStorage | INLINE | SHARED uses a shared string table: smaller files for repeated text, memory grows with the number of distinct strings |
flushThreshold | 65536 | Compressed bytes buffered before a write to the destination |
xmlBufferSize | 65536 | Uncompressed XML bytes buffered before compression |
cellReferences | false | Write a reference such as B7 on every cell |
date1904 | false | Use the 1904 date system |
zone | system default | Time zone for Instant and java.util.Date values |
closeOutput | true | Whether closing the writer closes the destination stream |
Worksheet options (SheetOptions.builder()): freezeRows, freezeColumns, columnWidths, column(index, Column) for width, column style and hidden columns, hideGridLines, hidden, tabColor, autoFitColumns, rowOutlineLevels, outlineSummaryAbove. They precede the cell data in the file, so they are fixed when the worksheet is added.
Dates and time zones#
Excel has no time zones; a cell holds a wall-clock date and time.
LocalDate,LocalDateTimeandLocalTimeare written as they are.ZonedDateTimeandOffsetDateTimeare written with their own local date and time; the zone or offset is dropped. 14:00 in New York is written as 14:00.Instantandjava.util.Datehave no wall-clock time of their own. They are converted in thezoneoption, by default the system default zone at the time the writer is created.Durationis written as a number of days and shown as[h]:mm:ss.
Unstyled dates get the viewer’s locale date format; a style without a number format keeps its font, fill and borders and gets that date format too. Dates the workbook’s date system cannot represent (before 1900-01-01, or before 1904-01-01 in the 1904 system, or after 9999-12-31) are written as ISO-8601 text.
Notes and limits#
- ExcelJS as a reader: by default Hypaxel omits cell references that follow from a cell’s position. That is valid and is read by Excel, LibreOffice, Apache POI and openpyxl, but ExcelJS fails on such files. Set
cellReferences(true)if your files are read with ExcelJS. - Excel limits apply: 1,048,576 rows, 16,384 columns and 32,767 characters per cell. Worksheet names have 1 to 31 characters, none of
: \ / ? * [ ], no leading or trailing apostrophe, and are unique ignoring case. Violations throw anXlsxException. - Numbers: Excel stores every number as a double.
longvalues beyond 2^53 andBigDecimalvalues with more than 15 significant digits lose precision; write them as text if exactness matters.NaNand infinities are written as#NUM!. - Formulas are stored without cached results; Excel calculates them when the file opens.
- Text: characters that XML cannot carry (control characters) are written with Excel’s
_xHHHH_escape, and unpaired surrogates are replaced with U+FFFD. - Large files: the ZIP container switches to ZIP64 automatically when a worksheet or the file passes 4 GiB.
- Styles belong to the writer that created them.
- Threads: a writer and its worksheets are not thread-safe. Use one writer per export; separate writers are independent.
Performance#
Writing#
Measured on an Apple M1 Max (10 cores, macOS 26.6) with OpenJDK 24.0.1 against FastExcel 0.20.2 and Apache POI 6.0.0, writing 10 columns per row (int, two strings, two doubles, BigDecimal, LocalDateTime, boolean, long, unique string) to a stream that discards the bytes. Hypaxel writes 100,000 rows in about 0.12 s and 1 million rows in about 1.2 s with the default deflate level 1. At the same compression level it is about 2.5 to 3 times faster than FastExcel, and about 8 to 9 times faster than Apache POI’s streaming writer (SXSSF). The typed, RowWriter and object-mapping paths allocate the same amount regardless of row count. About 70% of the time at level 1 is spent in the JDK’s Deflater, so the compression level decides most of the run time.
- Hypaxel, typed write118 ms, best
- Hypaxel, writeRows with a RowWriter118 ms, best
- Hypaxel, object mapping123 ms, best
- Hypaxel, addRow(Object...)123 ms, best
- Hypaxel, shared strings135 ms, 1.1×
- Hypaxel, compression level 6324 ms, 2.7×
- FastExcel, compression level 1352 ms, 3.0×
- FastExcel, default settings443 ms, 3.8×
- Apache POI SXSSF1,057 ms, 9.0×
| Case | Time | Allocated | File |
|---|---|---|---|
| Hypaxel, typed write | 118 ms | 0.17 MB | 3.9 MB |
| Hypaxel, writeRows with a RowWriter | 118 ms | 0.17 MB | 3.9 MB |
| Hypaxel, object mapping | 123 ms | 0.17 MB | 3.9 MB |
| Hypaxel, addRow(Object...) | 123 ms | 14.6 MB | 3.9 MB |
| Hypaxel, shared strings | 135 ms | 3.9 MB | 4.1 MB |
| Hypaxel, compression level 6 | 324 ms | 0.37 MB | 3 MB |
| FastExcel, compression level 1 | 352 ms | 261 MB | 6.9 MB |
| FastExcel, default settings | 443 ms | 262 MB | 5.9 MB |
| Apache POI SXSSF | 1,057 ms | 501 MB | 5.6 MB |
- Hypaxel, typed write1.2 s, best
- Hypaxel, writeRows with a RowWriter1.21 s, best
- Hypaxel, object mapping1.25 s, best
- Hypaxel, addRow(Object...)1.31 s, 1.1×
- Hypaxel, shared strings1.5 s, 1.3×
- Hypaxel, compression level 63.24 s, 2.7×
- FastExcel, compression level 13.01 s, 2.5×
- FastExcel, default settings4.22 s, 3.5×
- Apache POI SXSSF9.77 s, 8.1×
| Case | Time | Allocated | Peak RSS | File |
|---|---|---|---|---|
| Hypaxel, typed write | 1.2 s | 0.16 MB | 325 MB | 38.8 MB |
| Hypaxel, writeRows with a RowWriter | 1.21 s | 0.16 MB | 331 MB | 38.8 MB |
| Hypaxel, object mapping | 1.25 s | 0.17 MB | 326 MB | 38.8 MB |
| Hypaxel, addRow(Object...) | 1.31 s | 137 MB | 467 MB | 38.8 MB |
| Hypaxel, shared strings | 1.5 s | 30 MB | 366 MB | 41 MB |
| Hypaxel, compression level 6 | 3.24 s | 0.35 MB | 324 MB | 29.9 MB |
| FastExcel, compression level 1 | 3.01 s | 2,503 MB | 1,097 MB | 69.3 MB |
| FastExcel, default settings | 4.22 s | 2,487 MB | 1,064 MB | 60.7 MB |
| Apache POI SXSSF | 9.77 s | 4,712 MB | 866 MB | 56.9 MB |
Why writing is fast:
- No XML library. Markup is appended as precomputed ASCII byte arrays to one reusable buffer; text is transcoded from UTF-16 to UTF-8 and escaped in a single pass.
- No objects per cell. There are no cell, row or string objects, and no boxing in the typed overloads. Integers and doubles are formatted straight into the buffer; doubles use the Schubfach shortest-representation algorithm instead of
Double.toString. Date serials use integer arithmetic only. - Compact XML. Cell references (
r="B7") are only written after a gap. The format allows this, and it removes about 20% of the XML that has to be deflated. - Own ZIP container. Entries are deflated directly into the output buffer with data descriptors, so nothing is buffered per entry and the destination never has to seek.
Reading#
The 1M-row dataset of the write benchmark, written by Hypaxel once with inline strings (40.7 MB) and once with a shared string table (43.0 MB, 1M distinct strings), read against the FastExcel reader 0.20.2 and Apache POI 6.0.0’s event API (XSSFReader with a SAX handler). Every reader visits every cell with its typed accessors and must produce the same checksum. Hypaxel reads either file in about 0.7 s, about 4 times faster than FastExcel and 5 to 7 times faster than POI, and allocates the least. About 25% of its time is inflate and CRC-32 verification in the JDK.
- Hypaxel XlsxReader0.7 s, best
- FastExcel ReadableWorkbook2.69 s, 3.8×
- Apache POI XSSFReader + SAX3.27 s, 4.7×
| Case | Time | Allocated | Peak RSS |
|---|---|---|---|
| Hypaxel XlsxReader | 0.7 s | 322 MB | 354 MB |
| FastExcel ReadableWorkbook | 2.69 s | 3,913 MB | 732 MB |
| Apache POI XSSFReader + SAX | 3.27 s | 1,267 MB | 616 MB |
- Hypaxel XlsxReader0.69 s, best
- FastExcel ReadableWorkbook2.97 s, 4.3×
- Apache POI XSSFReader + SAX4.65 s, 6.7×
| Case | Time | Allocated | Peak RSS |
|---|---|---|---|
| Hypaxel XlsxReader | 0.69 s | 74 MB | 155 MB |
| FastExcel ReadableWorkbook | 2.97 s | 4,068 MB | 1,015 MB |
| Apache POI XSSFReader + SAX | 4.65 s | 7,886 MB | 827 MB |
Why reading is fast:
- Own XML pull parser over UTF-8 bytes. No StAX or SAX, no
char[]decoding of markup; names are compared as bytes and namespace prefixes are ignored by matching local names. - One-pass fast path for common cells. Ordinary shared-string and inline-string cells are recognized in a single scan; anything else (formulas, rich text, comments, unusual whitespace) falls back to the general parser, so both give the same result.
- No objects per cell. Rows are parallel primitive arrays reused from row to row; text stays UTF-8 until you ask for a
String, and shared strings are created once. - Correctly rounded number parsing without
Double.parseDouble. Clinger’s fast path for up to 15 digits, then the Eisel-Lemire algorithm for up to 19 digits; the JDK only handles the rare rest. Results are bit-identical toDouble.parseDouble. - Own ZIP reader. Positional reads and
java.util.zip.Inflaterdirectly into the parser’s buffer, which also lets several worksheets be read at once.
See Performance for methodology and reproduction, and Benchmarks for the full tables.
Building from source#
The source is at github.com/vensas/hypaxel, in the java/ directory. Report bugs at github.com/vensas/hypaxel/issues.
Requires JDK 17 or later. Maven comes from the wrapper.
cd java
./mvnw -B verify # compile for Java 17, run the tests, check 80% line coverageThe writer tests read every workbook back with Apache POI; the reader tests round-trip through the writer, read files written by POI, handcrafted packages and thousands of damaged files. The coverage report is written to target/site/jacoco/index.html.