SheetData and defaults

SheetData<T>

public record SheetData<T>(String name, Class<T> type, List<T> rows) {
    public static <T> SheetData<T> of(String name, Class<T> type, List<? extends T> rows);
}

Component	Meaning
name	The sheet name, subject to V-19 and V-20.
type	The sheet class, annotated with @ExcelSheet.
rows	The objects, in row order; the first element is data row 1.

• The sheet class is passed explicitly because the element type of a list is erased at runtime and an empty list has no element to inspect.
• The rows are copied into an unmodifiable list, so later changes to the original list do not affect the sheet.
• Null elements are kept by the copy and reported, at generation time, as a SheetsmithGenerationException with their row index.
• of accepts a list whose element type is a subtype of the sheet class: a List<PremiumCustomerRow> can be written with the sheet class CustomerRow without copying or casting. The columns are those of CustomerRow.
• The constructor and of throw NullPointerException for a null argument.
• Sheet names are not checked when the record is created: they are checked by generate, together with the other configuration errors.

Sheet name rules (checked by generate):

Rule	Code
1 to 31 characters	V-19
none of the characters \ / ? * [ ] :	V-19
does not start or end with an apostrophe '	V-19
unique within the workbook, ignoring case	V-20

Invalid names are rejected, never truncated or cleaned: names built from data must be cleaned by the caller (see recipe 13.15). Excel also reserves the name History, which is not rejected but must be avoided.

List<SheetData<?>> sheets = List.of(
        SheetData.of("Customers", CustomerRow.class, customers),
        SheetData.of("Invoice lines", InvoiceLine.class, lines));

SheetsmithDefaults

public record SheetsmithDefaults(String dateFormat, String dateTimeFormat, String numberFormat,
                                 TablePreset preset, String accentColor) {
    public static SheetsmithDefaults standard();
}

Component	Meaning	Standard value	Constraint
dateFormat	Default format of date cells, such as LocalDate values	yyyy-mm-dd	not null, not blank
dateTimeFormat	Default format of date-time cells, such as LocalDateTime values	yyyy-mm-dd hh:mm:ss	not null, not blank
numberFormat	Default format of numeric cells, integers included	"" (Excel “General”)	not null, may be empty
preset	Preset of sheet classes that declare INHERIT	NONE	not null, not INHERIT
accentColor	Accent colour of sheet classes that declare none	#4472C4	not null, a valid colour (empty not allowed)

The constructor throws IllegalArgumentException for invalid values, with these messages: dateFormat must not be blank, dateTimeFormat must not be blank, preset must not be INHERIT, accentColor 'X' is not a valid colour: expected #RRGGBB or the name of an IndexedColors constant; and NullPointerException for null components.

When a default format applies. A default format applies only when the effective style of the cell sets no format, that is when neither @ExcelColumn.format nor the dataFormat of any style in the cascade sets one. A data cell therefore takes its format from the first of these sources that sets one: the column format, the dataFormat of the cascade, the default format for its kind of value.

Kind of cell value	Default format used
date (LocalDate, CellValue.date)	dateFormat
date-time (LocalDateTime, CellValue.dateTime)	dateTimeFormat
number (any Number, CellValue.number)	numberFormat, if not empty
text, boolean, blank	none

numberFormat applies to every numeric cell, integers included: with #,##0.00, an integer column shows two decimals unless it has its own format, for example format = "0".

The accent colour is used only when the effective preset is not NONE.

DocumentProperties

public record DocumentProperties(String author, String application) {
    public static DocumentProperties standard();   // author "sheetsmith", application "sheetsmith"
}

Component	Meaning	Standard value
author	The author of the documents, shown by Excel in File, Info, and by the operating system among the file properties	sheetsmith
application	The application recorded as the creator of the documents	sheetsmith

• Values are written as they are.
• An empty value leaves the property out of the file, so it appears blank.
• Null components throw NullPointerException.
• Without configuration, both properties are sheetsmith, replacing the “Apache POI” values that the underlying library would otherwise record.

Sheetsmith.builder().documentProperties(new DocumentProperties("Example Ltd", "Billing")).build();
Sheetsmith.builder().documentProperties(new DocumentProperties("", "")).build();   // both left out

In Spring Boot, use sheetsmith.document.author and sheetsmith.document.application (section 10.3).