Preserve property descriptions during Gradle incremental compilation

[galenzo17]

Status

Draft. Seeking approach validation before adding performance benchmarks
and a repro on a spring-boot-internal module. Specifically requesting
sanity-check on the FieldValuesParser extension (the @FunctionalInterface
removal to add a default method).

Summary

When Gradle performs incremental compilation, unchanged @ConfigurationProperties
classes are passed to the annotation processor as .class files via the classes
parameter of JavaCompiler.getTask(). Since bytecode does not carry javadoc,
Elements.getDocComment() returns null for these elements and their property
descriptions are lost from spring-configuration-metadata.json.

This implements option 1 from the issue thread
(confirmed by @wilkinsona):
cache descriptions in a location outside CLASS_OUTPUT that Gradle does not clean
during incremental builds.

Approach

• New processor option org.springframework.boot.configurationprocessor.descriptionCacheLocation
  configures where the cache file lives (opt-in, zero behavior change when unset)
• .class-backed elements are detected via com.sun.source.util.Trees.getTree(),
  reusing the existing reflection wrapper in JavaCompilerFieldValuesParser
• On write, descriptions for .class-backed types are filled from cache before the
  JSON is emitted; then the cache is replaced with the current metadata
• Replace (not merge) strategy on cache update ensures deleted/de-annotated types are
  automatically pruned — no unbounded growth

Files changed

File	Change
FieldValuesParser	Added default hasSourceTree() (removed @FunctionalInterface — internal API)
JavaCompilerFieldValuesParser	hasSourceTree() using existing Trees instance
MetadataGenerationEnvironment	hasSourceTree() delegating to field values parser
ConfigurationMetadataAnnotationProcessor	New option, tracks .class-backed types, fills missing descriptions from cache on write, then refreshes cache
DescriptionCache (new)	File-based metadata cache with read/write/lookup
DescriptionCacheTests (new)	5 tests covering bug confirmation, JavaBean fix, record fix, staleness pruning, corrupt cache

Tests

• 5 new tests in DescriptionCacheTests — all pass
• All existing spring-boot-configuration-processor tests continue to pass
• Checkstyle clean

Scope and limitations

• In scope: Gradle + javac incremental compilation (the scenario in Configuration property descriptions may be lost when building incrementally #28075)
• Out of scope (follow-ups):
  • spring-boot-gradle-plugin should wire the descriptionCacheLocation option automatically
  • Kotlin/kapt uses a different compilation model and is not addressed here
  • Maven incremental builds are not tested

Alternatives considered

• Option 2 (non-incremental processor): would increase compile times for all users
• Option 3 (annotation-based descriptions instead of javadoc): would require
  ecosystem-wide migration of existing property descriptions from javadoc to a new
  annotation
• Merge-based cache update: would accumulate stale entries for deleted types;
  replace strategy is simpler and leverages the invariant that Gradle passes all
  annotated types every round

---

See gh-28075

[snicoll]

Thanks for the PR.

I am wondering why we wouldn't be able to re-read the generated metadata rather than storing things in a gradle specific location. This would also be a annotation processor only change that, if the Javadoc is not available, then take the value from the previous round.

[wilkinsona]

I am wondering why we wouldn't be able to re-read the generated metadata rather than storing things in a gradle specific location

Gradle deletes the previously generated metadata before incremental compilation begins.

[galenzo17]

Thanks both! I tried reading the previous metadata too, but Gradle clears it before the incremental build starts, so there's nothing left to read. That's why I went with the cache. Happy to take a different approach if you'd prefer one — otherwise, would it help if I put together some benchmarks to back this up?

[galenzo17]

Hi @snicoll @wilkinsona — friendly ping now that this area is getting attention. Given Gradle deletes the previous metadata before the incremental round, is the cache approach acceptable in principle? If yes, I'll mark this ready and add the Gradle-plugin wiring for descriptionCacheLocation; if you'd rather see a different approach, just point me at it and I'll rework.

[wilkinsona]

Thanks, @galenzo17, and thanks for your patience. We've managed to make some inroads into the PR backlog and hope to be able to give this PR the time that it deserves in the not too distant future.