Skip to content
Kaumei JDBCKaumei JDBCKaumei JDBC

JDBC Processor

The Kaumei JDBC annotation processor turns annotated Java interfaces into JDBC implementations at compile time. This specification defines the public contract between a JDBC interface and the generated implementation.

Detailed rules belong to the page that owns the topic. This overview provides the scope, the generated implementation contract, and a map of the specification pages.

Scope

Section titled “Scope”

The specification covers:

  • supported public annotations
  • processor configuration
  • converter discovery and lookup
  • Java-to-JDBC parameter binding
  • JDBC-to-Java result mapping
  • select, update, batch update, callable statement, and native JDBC methods
  • nullness behaviour for supported features

It does not define database-specific SQL syntax or driver behaviour. Those remain the responsibility of the selected JDBC driver and database.

JDBC interfaces

Section titled “JDBC interfaces”

A JDBC interface is an interface that directly declares at least one method annotated with @JdbcBatchUpdate, @JdbcCall, @JdbcNative, @JdbcSelect or @JdbcUpdate.

A JDBC interface must not extend another interface, except for the batch interface form defined in JDBC Update.

A JDBC interface must not declare type parameters. A JDBC method must not declare type parameters. Parameterized Java types with concrete type arguments, such as List<Customer>, are supported where defined by the method-specific rules.

Generated implementation

Section titled “Generated implementation”
❗️Generated implementation

For each processed JDBC interface, the processor generates a class named <InterfaceName>$Jdbc in the same package. The generated class implements the interface and has a public constructor that accepts a JdbcConnectionProvider. The provider supplies the JDBC Connection used by generated method calls.

The generated class is annotated with @Generated. If the target source file already exists, generation is invalid.

Annotations declared on the JDBC interface are not copied to the generated class. Generated-class and constructor annotations must be configured explicitly with @JdbcGeneration.

Only abstract instance methods declared directly in the JDBC interface participate in JDBC method generation. Static, default, and private methods do not participate. Each generated JDBC method must be defined by exactly one supported JDBC method annotation.

See Annotation Index.

Error handling

Section titled “Error handling”

Errors that prevent meaningful generation for the processor run are reported as compiler diagnostics. This includes invalid global processor configuration and structural errors for which no valid generated type can be produced.

When an error is limited to one JDBC method and the implementation class can still be generated, the generated method throws CodeGenerationException when it is invoked. This keeps the remaining valid JDBC methods usable and the generated class compilable.

Configuration supplied through a method parameter is dynamic and cannot be validated during annotation processing. An invalid dynamic configuration value is rejected by the generated method with IllegalArgumentException.

JDBC SQLException failures raised while executing generated code are wrapped in JdbcException. More specific runtime failures, such as missing or additional result rows, use the exception defined by the rule that detects them.

Specification map

Section titled “Specification map”
  • Annotation Index lists all public annotations, valid Java locations, and canonical rule pages.
  • Processor Configuration defines processor options, configuration types, defaults, overrides, reset behaviour, and multi-module configuration boundaries.
  • Nullness Contract defines shared nullness vocabulary, Optional<T> usage, and the project-wide nullness rule.
  • Converter Lookup defines converter discovery, scopes, names, type lookup, and dependency context.
  • Parameter Binding defines Java-to-JDBC parameter binding, SQL markers, record and collection expansion, Java-to-JDBC converters, and parameter nullness consequences.
  • Result Mapping defines JDBC-to-Java result mapping, column and row mapping, JDBC-to-Java converters, and result nullness consequences.
  • JDBC Select defines select execution, supported return forms, row-count handling, and select-specific error cases.
  • JDBC Update defines update execution, generated values, batch update methods, and batch lifecycle.
  • JDBC Call defines callable text, input and output parameters, output conversion, supported JDBC types, and driver boundaries.
  • JDBC Native defines native target lookup, target signatures, return types, nullness, checked exceptions, overloads, and JDBC resource ownership.