Support for JEP 401 (Value Classes) in ResultSet mapping to eliminate Object Identity overhead

[trueman06]

Requesting native support for mapping CQL rows directly into flattened Value Records (Project Valhalla).

[dkropachev]

I investigated the codebase to assess what would be needed to support JEP 401 Value Classes in the mapper.

Current State

The driver's mapper already has a well-structured pattern for handling immutable types through compile-time code generation. Notably, Java Record support already exists following this exact pattern:

• DefaultEntityFactory detects java.lang.Record and sets mutable=false, getterStyle=FLUENT
• MapperProcessor accepts ElementKind.RECORD alongside ElementKind.CLASS
• For immutable types, the generated get() method collects column values into local variables and calls the all-args constructor directly

This existing Record support serves as a direct template for Value Class support.

What Would Need to Change

The changes are minimal to moderate, concentrated in mapper-processor:

1. Detection — Add a new language variant in DefaultEntityFactory (similar to JAVA14_RECORD) that detects value classes via their superclass or modifier once the JDK defines them in javax.lang.model.

2. Processor kind acceptance — Update MapperProcessor.processAnnotatedTypes() and EntityUtils.asEntityElement() to accept the new ElementKind for value classes.

3. Null-safety in generated code — This is the hardest part. The current generated get() code freely assigns null to properties (in lenient mode, or when a CQL column is null). Value classes cannot be null by default, so the code generator would need to either:

   • Use default/zero values instead of null for value-typed properties
   • Require all value-class properties to map to non-nullable CQL columns
   • Emit compile-time errors when null-incompatible mappings are detected

4. No changes needed in core — Row, ResultSet, CodecRegistry, and the GettableByIndex/GettableByName interfaces are type-agnostic and would work as-is.

Assessment

JEP 401 is still a preview feature (as of JDK 24), and the exact representation of value classes in the annotation processing API (javax.lang.model) is not yet stable. Implementing support now would risk building against an API that changes before finalization.

The architecture is already well-prepared — once JEP 401 is finalized, the implementation would follow the established Record support pattern closely. The main design decision to resolve at that point will be the null handling strategy, since CQL's nullable column semantics don't map cleanly to value classes' non-nullable default.