How generation works

Converters

Every field value is turned into a cell value by a converter before being written. Built-in converters cover text, numbers, booleans, enums, LocalDate and LocalDateTime. Any other type needs a converter, declared on one column (field converter) or registered for a type across the application (application converter). The converter of each column is chosen once, from the declared type of the field. Converters are described in section 9.

Lifecycle of a generation

When generate is called, the library:

1. validates the input: the list is not empty, sheet names are valid and unique (V-18 to V-20);
2. for each distinct sheet class, obtains its validated metadata (V-01 to V-09, V-13 to V-17) and binds a converter to each column (V-10 to V-12), using the per-class caches when available;
3. if any configuration error was found, throws one SheetsmithConfigurationException listing all of them, and writes nothing;
4. creates a new workbook and records the document properties;
5. writes each sheet: title, header, data rows (reading each value, converting it, choosing the effective style), then freeze pane, auto-filter and column widths;
6. serialises the workbook to the stream, flushes the stream, and releases the workbook.

Data problems found during step 5 stop the generation with a SheetsmithGenerationException. Nothing is written to the output in that case.

Caching and thread safety

• The metadata of a sheet class (columns, resolved styles, value accessors) is computed and validated on first use, then cached per class and shared by every generator. The cache does not retain class loaders, which matters with development tools that restart the application.
• The converter binding of a sheet class is cached per generator, because it depends on the converters configured on that generator.
• A class that fails validation is not cached: it is rejected at every call, with the same errors, until it is fixed.
• A generator is immutable and thread-safe. Every generation builds its own workbook, so concurrent calls do not interfere. Converters are shared between concurrent generations and must be thread-safe.
• Within one generation, the effective style of each distinct combination of column, row parity, first or last row and kind of value is computed once per sheet and reused for every cell with that combination. Equal effective styles share one Excel cell style, fonts and data formats are deduplicated, so the number of cell styles in a file depends on the number of distinct styles and never on the number of cells.