Spring Boot integration

What the auto-configuration does

With sheetsmith-spring-boot-starter on the classpath, the auto-configuration SheetsmithAutoConfiguration (registered in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports, active when Sheetsmith is on the classpath) registers:

1. a Sheetsmith bean, unless the application defines its own bean of that type. The auto-configured bean is built with:
   • the defaults bound from the sheetsmith.* properties;
   • the document properties bound from sheetsmith.document.*;
   • a SpringConverterFactory for field converters;
   • every CellConverter bean of the context as an application converter, registered for its generic type;
2. a SheetsmithStartupValidator, only when sheetsmith.validation.packages is not empty.

No annotation is required in the application: inject Sheetsmith where needed.

Defining your own Sheetsmith bean

The auto-configured bean is declared with @ConditionalOnMissingBean. When the application defines a Sheetsmith bean, the auto-configured one backs off and the application bean is used as it is. In that case the application is responsible for its configuration: the sheetsmith.* defaults and document properties and the converter beans are not applied automatically to a bean built by the application. The startup validator, when enabled, uses whichever Sheetsmith bean is in the context.

@Configuration
class SheetsmithConfiguration {

    @Bean
    Sheetsmith sheetsmith(ConfigurableListableBeanFactory beanFactory, SheetsmithProperties properties) {
        return Sheetsmith.builder()
                .defaults(properties.toDefaults())
                .documentProperties(properties.toDocumentProperties())
                .converterFactory(new SpringConverterFactory(beanFactory))
                .converter(Instant.class, new InstantConverter(ZoneId.of("Europe/Rome")))
                .build();
    }
}

SheetsmithProperties.toDefaults() and toDocumentProperties() convert the bound properties; SpringConverterFactory is public and can be reused.

Startup validation

When sheetsmith.validation.packages lists at least one package, the SheetsmithStartupValidator runs once all singletons are created:

• it scans the packages and their subpackages for types annotated directly with @ExcelSheet: concrete and abstract classes, records, interfaces, and nested classes, static or not;
• annotation types are not validated, even when annotated with @ExcelSheet, and neither are types only meta-annotated with it through another annotation;
• it calls validate on each type with the Sheetsmith bean of the context, so converter beans and the Spring converter factory are taken into account;
• the errors of all invalid types are collected into one SheetsmithConfigurationException, which stops the application.

Mistakes in sheet classes then surface at startup instead of at the first generation. An interface annotated with @ExcelSheet is always reported (it can have no instance fields, so it violates V-02), which is intended: the annotation does not belong on an interface.

Public types of the auto-configuration module

Type	Role
SheetsmithAutoConfiguration	The auto-configuration. Instantiated by Spring Boot, not by applications.
SheetsmithProperties (with nested records Formats, Document, Validation)	The bound properties; toDefaults() and toDocumentProperties() convert them.
SpringConverterFactory	Creates field converters from the application context.
SheetsmithStartupValidator	The startup validator (a SmartInitializingSingleton).