Introduction

What sheetsmith is

sheetsmith is an open source Java library that generates Excel files in the .xlsx format from lists of Java objects. It is built on Apache POI and integrates with Spring Boot through an auto-configuration, while its core works in any Java application.

The structure and the appearance of each sheet are described once, with annotations placed on a Java class called the sheet class. The content of each sheet comes from the objects passed at runtime, one object per data row. The library then writes the title, the header row, the data rows, the styles, the formats and the layout options, and returns the file.

What sheetsmith does

sheetsmith provides the following capabilities in version 1.0.0.

Capability	Description
Generation component	A single component, Sheetsmith, that generates a complete workbook and either returns it as a byte[] or writes it to an OutputStream supplied by the caller.
Multi-sheet workbooks	One workbook can contain any number of sheets, each with its own sheet class, in the order chosen by the caller.
Annotation model	Eight annotations describe the sheet, its columns, its named styles, its shared style sheets and the places where styles apply.
Opt-in columns	Only fields explicitly annotated become columns. Records, classes and inherited fields are supported.
Mandatory, stable column order	Every column declares its position, so the order never depends on reflection.
Complete styling	Every cell formatting attribute exposed by Apache POI can be declared: alignment, wrapping, rotation, indentation, borders and border colours, fills, fonts, data formats, protection flags and quote prefix.
Role-based styling	Styles can target every data cell, odd and even rows, the first and last data row, the first and last column, a single column, the header, the header of a single column and the title.
Deterministic cascade	Styles combine attribute by attribute following a fixed, documented order, so the result of any combination is predictable.
Presets	Three ready-made table styles (LIGHT, MEDIUM, DARK) generated from a single accent colour, which can be partially overridden.
Shared style sheets	Named styles can be declared once in a style sheet class and reused by any number of sheet classes, which allows every report of an application or an organisation to share the same corporate look.
Native cell types	Text, numbers, booleans, enums, LocalDate and LocalDateTime are written as native Excel values.
Converters	Any other type is supported through converters, declared on a single column or registered for a type across the whole application.
Default formats	Application-wide default formats for dates, date-times and numbers, applied when a cell has no explicit format.
Layout options	Optional title row merged across the table, frozen header, auto-filter, explicit column widths, automatic column sizing with a fallback for environments without fonts, and an outer frame around the table.
Document properties	Configurable author and application recorded in every generated file.
Fail-fast validation	Twenty validation rules (V-01 to V-20) detect configuration mistakes before anything is written. All errors are reported together, with a stable code, the class and the element involved.
Startup validation	In Spring Boot applications, the sheet classes of chosen packages can be validated when the application starts.
Precise runtime errors	Data problems are reported with the sheet name, the data row and the field.
Thread safety	A generator is immutable and thread-safe, and caches the metadata of each sheet class after the first use.

Scope of version 1.0.0

Version 1.0.0 writes .xlsx files only and builds each workbook entirely in memory before writing it. The following are not part of the library: reading Excel files, the legacy .xls format, formulas, charts, images, conditional formatting, data validation, cell comments, sheet protection, native Excel tables and translation of header texts. Header texts are written exactly as declared, so localisation, when needed, is performed by the application before or around the generation.

Planned and evaluated evolutions are listed in section 15.