Nullness Contract
Kaumei JDBC uses JSpecify nullness information when it generates JDBC code. Nullness is part of the public behaviour contract.
Vocabulary
Section titled “Vocabulary”The specification uses these terms:
nullable: the Java type may holdnull.non-null: the Java type must not holdnull.unspecified: the Java type has no nullness information Kaumei JDBC can use.
unspecified is the default when no relevant JSpecify annotation is present.
Kaumei JDBC does not treat unspecified as non-null.
It also does not add extra null checks only because a type is unspecified.
Kaumei JDBC reads nullness from method parameters, return types, converter signatures, record components, and constructor parameters where the specific mapping rule uses those elements.
For non-null values, generated code rejects null at the boundary where
Kaumei JDBC can observe the value.
For nullable values, generated code accepts null and maps it according to
the page-specific rule.
For unspecified values, generated code preserves the existing Java/JDBC
behaviour unless a more specific rule applies.
Primitive Java types are always non-null. Reference types need JSpecify information when the distinction matters.
Java Optional
Section titled “Java Optional”Optional<T> models absence as a Java value.
It is primarily supported for result values.
Optional<T> is not supported for JDBC method parameters.
Use a nullable parameter when SQL-NULL should be bound.
Where Optional<T> is supported,
the Optional<T> object itself is non-null and the contained value type T is
treated as non-null.
Do not combine Optional<T> with nullable annotations.
Optional.empty() must not hide two different meanings unless a page explicitly
allows that behaviour.
For select methods,
JDBC Select defines the difference between no row and a
row whose selected column value is SQL-NULL.
Ownership
Section titled “Ownership”Page-specific consequences belong on the corresponding specification pages:
- parameter nullness belongs to Parameter Binding
- result and column nullness belongs to Result Mapping
- select no-row behaviour belongs to JDBC Select
- native method signature compatibility belongs to JDBC Native
Those pages may add stricter local rules.
Test coverage
Section titled “Test coverage”
❗️Value nullness
❗️Simple converter nullness
❗️Statement converter nullness