refactor: make @SimpleBuilder a built-in template annotation (#246) - #256
Merged
AndreasIgel merged 12 commits intoAug 16, 2026
Merged
Conversation
The class-level Javadoc and docs/CONFIGURATION.md implied that @SimpleBuilder is inherited by subclasses, but the annotation was not meta-annotated with @inherited. As a result BuilderProcessor, which collects types via RoundEnvironment.getElementsAnnotatedWith(...), only produced builders for the exact type carrying @SimpleBuilder and not for unannotated subclasses. Add @inherited to @SimpleBuilder so subclasses are treated as if they also carried the annotation, mirroring the existing behaviour of @SimpleBuilder.Template (which is already @inherited). Update the Javadoc to document the inheritance explicitly and clarify the CONFIGURATION.md wording. @Ignore4BuilderGeneration still suppresses generation for the exact type it is placed on, so opt-outs continue to work as before. Add SimpleBuilderInheritanceTest covering direct inheritance, the opt-out interaction, and multi-level (grandchild) inheritance. Closes java-helpers#244 Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…ance Rename SimpleBuilderInheritanceTest to BuilderAnnotationInheritanceTest so the name reflects that it covers both builder-triggering annotations. Add unannotatedSubclassGetsBuilderFromInheritedTemplate, which verifies that a custom @inherited template annotation (meta-annotated with @SimpleBuilder.Template) propagates to unannotated subclasses, matching the existing behaviour of @SimpleBuilder itself. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
The Template Javadoc and CONFIGURATION.md "Template Annotations" section did not explain that @SimpleBuilder.Template is @inherited, nor that a custom template annotation must additionally declare @inherited to propagate to unannotated subclasses. Add explicit documentation and an example showing the @inherited custom annotation pattern. Also move assertNoBuilderGenerated to ProcessorAsserts so it is shared by BuilderAnnotationInheritanceTest and Ignore4BuilderGenerationTest instead of being duplicated as a private helper in each test class. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
While @SimpleBuilder and @inherited template annotations now correctly trigger builder generation for unannotated subclasses, the configuration options declared on the parent's @SimpleBuilder(options = ...) or template are not yet applied to inherited subclass builders — they use default options instead. This is tracked separately in issue java-helpers#245. Add caveats to the SimpleBuilder Javadoc, the CONFIGURATION.md Template Annotations section, and the Template Annotations Not Working troubleshooting section so users are not surprised by this limitation. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Add explicit guidance that @SimpleBuilder.Template is a meta-annotation for custom annotation declarations (@interface) only and cannot be placed directly on a class or record. @SimpleBuilder is for direct one-off annotation of classes/records. - SimpleBuilder.java: add 'When to use' section to class-level Javadoc - SimpleBuilder.Template Javadoc: state it can only be placed on annotation types (ANNOTATION_TYPE), not on classes/records - CONFIGURATION.md 'Template Annotations': add comparison table and introductory paragraph - CONFIGURATION.md troubleshooting: add item about @SimpleBuilder.Template not being a class annotation Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…Javadoc Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…arget The compiler and IDE already enforce @target(ANNOTATION_TYPE) and show a clear error when @SimpleBuilder.Template is placed on a class/record, so this troubleshooting item adds no value. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…lpers#246) Co-Authored-By: Andreas Igel <andreas.igel@computacenter.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Make
@SimpleBuildera built-in template annotation and drive all builder-triggering annotation discovery through a single path.Before,
BuilderProcessorhad two discovery branches: one for@SimpleBuilderand one for annotations meta-annotated with@SimpleBuilder.Template.BuilderConfigurationReaderthen duplicated this split by reading inline@SimpleBuilder.Optionsand template options separately. This change unifies both:@SimpleBuilderis now meta-annotated with@SimpleBuilder.Template.BuilderProcessorno longer special-cases@SimpleBuilder;extractingAnnotationsWithTemplatediscovers any annotation meta-annotated with@SimpleBuilder.Template.BuilderConfigurationReaderresolves configuration per inheritance scope: it extracts the effective configuration from any template annotation, with@SimpleBuildertaking precedence over other templates in the same scope, and direct annotations overriding inherited ones.@SimpleBuilder.Template.optionsnow defaults to an empty@Options(), so custom templates can omit explicit options and still pick up built-in defaults.Verification
mvn -pl core,processor,example test -ampasses: Processor 342 tests pass