AP and KSP: Generate a DTO Builder¶

This guide implements a small source generator: @GenerateBuilder produces a fluent builder for an immutable DTO. You will read the DTO structure, generate typed setters and a constructor call, and report unsupported input during compilation. The Java and Kotlin implementations use the same processor foundations as Kora itself.

What You'll Build¶

A shared @GenerateBuilder annotation artifact
A Java processor based on AbstractKoraProcessor and a Kotlin processor based on BaseSymbolProcessor
CreateUserBuilder with name(...), email(...) and build()
A runnable console example, diagnostics and incremental metadata

What You'll Need¶

JDK 25 or later, Gradle 9+ Wrapper and an editor
Kotlin 2.4.20 and KSP 2.3.12 for the Kotlin branch
Kora 2.0.0.RC2 processor-common artifacts
Familiarity with Java records or Kotlin data classes

Prerequisites¶

An independent processor example

Use Getting Started for JDK and Wrapper setup. Create a separate project for this guide and choose Java or Kotlin application sources. The complete build scripts below configure a console application.

The Neo4j module shows ordinary runtime wiring; this example teaches source generation independently. No running application graph or external infrastructure is required. Commands run from the new project root.

Overview¶

A DTO with several constructor parameters is easy to build positionally, but named builder calls make call sites readable when several fields have the same type. The processor removes repetitive builder code while preserving the DTO’s declared field types. Adding a field changes the generated API on the next compilation.

Runtime and processor artifacts¶

builder-annotation contains only the annotation. The application depends on it through implementation; compiler helpers belong only to builder-annotation-processor or builder-symbol-processor. The generated builder is an ordinary object created at the call site. It needs neither @Component nor a graph node.

The Kora processor pattern¶

Java extends AbstractKoraProcessor, declares supported ClassName values and receives grouped AnnotatedElement inputs. Kotlin extends BaseSymbolProcessor, implements processRound and defers unresolved symbols through validateAll. Both validate the model, create a Poet type and attach diagnostics to the input declaration. Service entries make the compiler discover the processors.

Supported models and required fields¶

Java supports public top-level non-generic records in named packages with at least one component. Kotlin supports public top-level non-generic data classes with a public primary constructor and required, non-null val parameters. Kotlin var, nullable, default-valued and vararg constructor parameters are rejected. A Java record component Object equals is also rejected: its fluent setter would collide with Object.equals(Object). The diagnostic points to the component instead of an invalid generated file.

Every builder field is required. In Java, reference fields cannot be null when build() runs; primitive state is boxed internally so an unset int is distinguishable from an explicitly supplied 0. Kotlin uses nullable private state and requireNotNull before construction. This is the builder contract; Java’s direct record constructor remains unchanged.

Annotation and DTO¶

Java Kotlin

Create builder-annotation/src/main/java/example/builder/GenerateBuilder.java:

package example.builder;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
public @interface GenerateBuilder {}

Create builder-annotation/src/main/kotlin/example/builder/GenerateBuilder.kt:

package example.builder

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.BINARY)
annotation class GenerateBuilder

CLASS / BINARY retention supports compile-time discovery and the isolating AP contract. Declare the DTO:

Java Kotlin

src/main/java/example/app/CreateUser.java:

package example.app;

import example.builder.GenerateBuilder;

@GenerateBuilder
public record CreateUser(String name, String email) {}

src/main/kotlin/example/app/CreateUser.kt:

package example.app

import example.builder.GenerateBuilder

@GenerateBuilder
data class CreateUser(val name: String, val email: String)

Dependencies and Project Layout¶

Select the application source language, then choose one Gradle DSL. The source language and script language are independent; save only one build script per project.

Root settings:

Java Kotlin

Groovy — settings.gradleKotlin DSL — settings.gradle.kts

rootProject.name = "builder-guide"
include("builder-annotation", "builder-annotation-processor")

rootProject.name = "builder-guide"
include("builder-annotation", "builder-annotation-processor")

Groovy — settings.gradleKotlin DSL — settings.gradle.kts

rootProject.name = "builder-guide"
include("builder-annotation", "builder-symbol-processor")

rootProject.name = "builder-guide"
include("builder-annotation", "builder-symbol-processor")

Root application build:

Java Kotlin