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	Value range	Unset support	Dynamic support
@JdbcBatchSize	1000	>= 1	no	yes
@JdbcFetchDirection	unset	enum	yes	yes
@JdbcFetchSize	unset	>= 0	yes	yes
@JdbcMaxRows	unset	>= 0	yes	yes
@JdbcNoMoreRows	THROW_EXCEPTION	enum	no	no
@JdbcNoRows	THROW_EXCEPTION	enum	no	no
@JdbcQueryTimeout	unset	>= 0	yes	yes
@JdbcResultSetConcurrency	unset	enum	yes	yes
@JdbcResultSetType	unset	enum	yes	yes
@JdbcConfig.generatedClassSuffix	$Jdbc	suffix	no	no
@JdbcConfig.maxCollectionPlaceholders	1000	>= 1	no	no
@JdbcConfig.maxTotalPlaceholders	2000	>= 1	no	no
@JdbcConfig.returnGeneratedValues	GENERATED_KEYS	enum	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. Integer option values outside their value range are rejected by the annotation processor for constant values. Invalid global processor configuration is a compiler error and does not become a generated runtime fallback. Invalid dynamic values are rejected by the generated method with IllegalArgumentException. For annotations with unset support, the static -1 sentinel remains valid as the unset value. For @JdbcQueryTimeout, @JdbcFetchSize, and @JdbcMaxRows, 0 keeps the JDBC meaning of no timeout, driver default, or no row limit.

For a scalar @JdbcSelect, result-set type, result-set concurrency, fetch direction, query timeout, and fetch size are applied normally. If no fetch size is configured, the generated implementation uses 1, or 2 when it must detect an additional row.

@JdbcMaxRows does not apply to scalar selects. The generated implementation limits the result internally to one row, or two rows when it must detect an additional row. A method-level or parameter-level @JdbcMaxRows on a scalar select is therefore invalid because the annotation is unused.

@JdbcConfig.generatedClassSuffix defines the suffix used for generated implementation classes. The default generates the class name InterfaceName$Jdbc. For example, generatedClassSuffix = "Impl" generates InterfaceNameImpl. The suffix must be a non-blank Java class name suffix. Invalid suffix values are processor errors.

@JdbcConfig.maxCollectionPlaceholders limits one dynamic array or List expansion created by :param.{values} or :param.*. The default is 1000. Values above the configured limit are rejected by the generated method with JdbcException.

@JdbcConfig.maxTotalPlaceholders limits the total number of JDBC ? placeholders in one generated method call. The default is 2000. The total includes plain :param markers, statically known record value expansion, and dynamically expanded array or List elements. When array or List values determine the final total at runtime, violations are rejected by the generated method with JdbcException.

❗️@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.