Skip to content
Kaumei JDBC Kaumei JDBC Kaumei JDBC

Specification Overview

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, 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.

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.

Only instance methods that are not default methods and not static methods participate in JDBC method generation. Each generated JDBC method must be defined by exactly one supported JDBC method annotation.

Additional generated-class and constructor annotations are configured with @JdbcGeneration. See Annotation Index.

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 Native defines native target lookup, target signatures, return types, nullness, checked exceptions, overloads, and JDBC resource ownership.