Processor Configuration

General configuration

The annotation processor can be configured with annotation processor options or with one type annotated with @JdbcConfig. The annotation processor itself supports Java 17 or newer.

Annotation processor options

Options	Description	Default
io.kaumei.jdbc.processor.config	A fully qualified @JdbcConfig type.	unset
io.kaumei.jdbc.processor.debugfolder	The folder for annotation processor debug output.	unset
io.kaumei.jdbc.processor.loglevel	The annotation processor log level.	ERROR

• If io.kaumei.jdbc.processor.config is set, it must point to a type annotated with @JdbcConfig. The value must be the fully qualified type name. Invalid values are rejected by the annotation processor. This option is useful when incremental compilation prevents automatic discovery of the configuration type.
• If io.kaumei.jdbc.processor.debugfolder is set, the annotation processor dumps its internal state to that folder. This is useful for debug sessions.
• io.kaumei.jdbc.processor.loglevel changes the annotation processor log level. Supported values are: ERROR, WARN, INFO, DEBUG.

Configuration type

The annotation processor can be configured by annotating a type with @JdbcConfig or by an annotation processor option (see above). This type defines default values for the annotation processor run.

@JdbcConfig may be placed on a class or on a pure configuration interface. It must not be placed on a JDBC service interface that declares @JdbcSelect, @JdbcUpdate, @JdbcBatchUpdate, or @JdbcNative methods.

Supported annotations

Annotation	Default	Unset support	Dynamic support
@JdbcBatchSize	1000	no	yes
@JdbcFetchDirection	unset	yes	yes
@JdbcFetchSize	unset	yes	yes
@JdbcMaxRows	unset	yes	yes
@JdbcNoMoreRows	THROW_EXCEPTION	no	no
@JdbcNoRows	THROW_EXCEPTION	no	no
@JdbcQueryTimeout	unset	yes	yes
@JdbcResultSetConcurrency	unset	yes	yes
@JdbcResultSetType	unset	yes	yes
@JdbcConfig.returnGeneratedValues	GENERATED_KEYS	no	no

Annotations with unset support can suppress an inherited value when used without an explicit value. For example, @JdbcQueryTimeout() on a method suppresses a timeout inherited from the interface or configuration type.

Constant and dynamic annotation values

Configuration annotations can define constant values on a configuration type, JDBC interface, or JDBC method. Some configuration annotations can also be placed on one method parameter. In that form, the value is supplied by the caller at runtime and overrides constant values for that method call.

Dynamic parameter values are method-local. They do not change the selected @JdbcConfig, interface-level configuration, or method-level constant annotations.

Only annotations whose Java target includes PARAMETER support dynamic parameter values. For example, @JdbcBatchSize may be placed on an @JdbcBatchUpdate method for a constant batch size or on one method parameter for a runtime batch size. @JdbcBatchSize values must be at least 1.

❗️@JdbcQueryTimeout ❗️@JdbcQueryTimeout ❗️@JdbcQueryTimeout ❗️JdbcBatchSize ❗️JdbcQueryTimeout ❗️JdbcConfig.returnGeneratedValues ❗️JdbcConfig.returnGeneratedValues

Define a parent config

With @JdbcConfig(parent = ...) one parent configuration can be defined. Parent configuration is applied before child configuration. The child configuration overrides the parent configuration.

Define additional converters

Static methods inside the configuration type are global converters when they are annotated with either @JdbcToJava or @JavaToJdbc.

@JdbcConfig(converter = {...}) adds additional global converter types. For each referenced type, methods explicitly annotated with @JdbcToJava or @JavaToJdbc are included in converter lookup.

❗️@ConfigSpec.parent ❗️@ConfigSpec.converter ❗️@ConfigSpec.converter ❗️@ConfigSpec.converter

Multi-module configuration

Each module that runs the annotation processor should define its own @JdbcConfig or explicitly select one with io.kaumei.jdbc.processor.config.

The selected configuration type is the module boundary for processor configuration. All types referenced from that configuration, including parent configurations and converter classes, must be visible during annotation processing for that module.

A shared module may provide a configuration type or converter classes. The processing module must reference the shared configuration or converters explicitly from its selected configuration.