Converter Lookup

Kaumei JDBC selects converters during parameter binding and result mapping. Converter preparation and resolution happen before code generation; generated code uses the converters prepared for the processed JDBC method and does not discover additional converters.

Discovery and scopes

Converters are discovered only from reachable places:

• built-in converters belong to the basic scope
• converters declared directly in a JDBC interface belong to that interface’s local scope
• converters declared in the selected @JdbcConfig type belong to the global scope
• converters referenced by @JdbcConfig(converter = ...) belong to the global scope
• converters found by inspecting a used Java type belong to the global scope

Used Java types come from JDBC method parameters, JDBC method return types, and nested converter dependencies needed for those parameters or return types. Converter definitions may be named or unnamed. Named converters are selected only by their names with @JdbcConverterName; type lookup does not fall back to a named converter.

Annotated converter methods or constructors outside the reachable paths are ignored. When used-type inspection finds an unnamed converter method or constructor, that converter is discovered through the used type and belongs to the global scope. Every discovered converter belongs to exactly one scope.

Converter names

❗️Named Java-to-JDBC converters

A converter is named only when its @JavaToJdbc or @JdbcToJava annotation declares a name. Converters without a declared name participate in type lookup. Named converters are selected only by @JdbcConverterName.

Blank converter names are invalid. This applies to:

• @JavaToJdbc("...")
• @JdbcToJava("...")
• @JdbcConverterName("...")

@JdbcConverterName has no unnamed form. Its value selects a named converter and must not be blank.

Names are matched exactly. Kaumei JDBC does not trim names before matching them. Use stable, explicit names when a converter must be selected by name.

General search order

For a JDBC interface, scopes are searched in this order:

1. local scope of the JDBC interface
2. global scope
3. basic scope

For name lookup and exact type lookup, the first matching converter wins. Java-to-JDBC hierarchy lookup has an additional specificity rule: a converter for a more specific Java type wins over a converter for a less specific Java type, even when the less specific converter is in an earlier scope.

If no discovered converter matches an unnamed type lookup, Kaumei JDBC may then inspect the used Java type.

Name lookup

@JdbcConverterName requests name-based lookup. Name lookup is exact and does not inspect the used Java type.

For parameter binding, the name is read from @JdbcConverterName on the method parameter. For result mapping, the name is read from @JdbcConverterName on the method.

The selected converter must also be compatible with the use. Parameter-binding compatibility is defined in parameter binding. Result-mapping compatibility is defined in result mapping.

If no converter with the requested name exists, or the converter is incompatible, converter selection is invalid.

Java-to-JDBC type lookup

Unnamed parameter binding uses @JavaToJdbc type lookup. The lookup first checks for an exact type match in the general search order.

If no exact match exists, Kaumei JDBC checks assignable Java supertypes. For each converter type candidate, the local, global, and basic scopes are searched before the next less specific type candidate is considered. A more specific converter input type wins over a less specific converter input type, even when the less specific converter is in an earlier scope.

An unnamed Java-to-JDBC converter matches when the method parameter type is a subtype of the converter input type. If multiple matching converter input types are unrelated in the type hierarchy, converter selection is ambiguous and invalid.

Kaumei JDBC inspects the used Java type only after exact and hierarchy lookup fail.

If no converter is found, the next parameter-binding rule is described in parameter binding.

JDBC-to-Java type lookup

Unnamed result mapping uses @JdbcToJava type lookup. The lookup checks for an exact type match in the general search order. It does not search the Java type hierarchy.

Only after exact lookup fails does Kaumei JDBC inspect the used Java type.

If no converter is found, the next result-mapping rule is described in result mapping.

Dependency context

Nested converter lookup uses the owning scope of the converter that needs the dependency. A local converter searches its owning JDBC interface’s local scope, then global, then basic. A global converter searches global, then basic. A basic converter searches only the basic scope.

This applies to record component converters, row converter column converters, constructor parameter converters, and converter method parameter converters.