Builder extensibility (#10838)

* Support for builder extensibility
* Jackson builder extension
* Support for detached blueprint
* Working on the test for builder codegen
* Documentation update

Author: tomas-langer

builder/README.md

@@ -62,12 +62,12 @@ There are a few rules we required and enforce:
 2. Blueprint interface MUST be package private
 3. Blueprint interface must have a name that ends with `Blueprint`; the name before `Blueprint` will be the name of the prototype
 4. In case we use the blueprint -> prototype -> runtime type use case (see below):
-   1. The blueprint must extend `Prototype.Factory<RuntimeType>` where `RuntimeType` is the type of the runtime object
-   2. The runtime type must be annotated with `@RuntimeType.PrototypedBy(PrototypeBlueprint.class)`
-   3. The runtime type must implement `RuntimeType.Api<Prototype>`
-   4. The runtime type must have a `public static Prototype.Builder builder()` method implemented by user
-   5. The runtime type must have a `public static RuntimeType create(Prototype)` method implemented by user
-   6. The runtime type must have a `public static RuntimeType create(Consumer<Prototype.Builder>)` method implemented by user
+    1. The blueprint must extend `Prototype.Factory<RuntimeType>` where `RuntimeType` is the type of the runtime object
+    2. ~~The runtime type must be annotated with `@RuntimeType.PrototypedBy(PrototypeBlueprint.class)`~~
+    3. The runtime type must implement `RuntimeType.Api<Prototype>`
+    4. The runtime type must have a `public static Prototype.Builder builder()` method implemented by user
+    5. The runtime type must have a `public static RuntimeType create(Prototype)` method implemented by user
+    6. The runtime type must have a `public static RuntimeType create(Consumer<Prototype.Builder>)` method implemented by user
 
 ## Use Cases
 
@@ -225,20 +225,23 @@ The API has to sections:
 
 Annotations:
 
-| Annotation                  | Required | Description                                                                                                                                                                                                  |
-|-----------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `Prototype.Blueprint`       | `true`   | Annotation on the blueprint interface is required to trigger annotation processing                                                                                                                           |
-| `Prototype.Implement`       | `false`  | Add additional implemented types to the generated prototype                                                                                                                                                  |
-| `Prototype.Annotated`       | `false`  | Allows adding an annotation (or annotations) to the generated class or methods                                                                                                                               |
-| `Prototype.FactoryMethod`   | `false`  | Use in generated code to mark static factory methods, also can be used on blueprint factory methods to be used during code generation, and on custom methods to mark static methods to be added to prototype |
-| `Prototype.Singular`        | `false`  | Used for lists, sets, and maps to add methods `add*`/`put*` in addition to the full collection setters                                                                                                       |     
-| `Prototype.SameGeneric`     | `false`  | Use for maps, where we want a setter method to use the same generic type for key and for value (such as `Class<T> key, T valuel`)                                                                            |
-| `Prototype.Redundant`       | `false`  | A redundant option will not be part of generated `toString`, `hashCode`, and `equals` methods (allows finer grained control)                                                                                 |
-| `Prototype.Confidential`    | `false`  | A confidential option will not have value visible when `toString` is called, only if it is `null` or it has a value (`****`)                                                                                 |
-| `Prototype.CustomMethods`   | `false`  | reference a class that will contain declarations (all static) of custom methods to be added to the generated code, can add prototype, builder, and factory methods                                           |
-| `Prototype.BuilderMethod`   | `false`  | Annotation to be placed on factory methods that are to be added to builder, first parameter is the `BuilderBase<?, ?>` of the prototype                                                                      |
-| `Prototype.PrototypeMethod` | `false`  | Annotation to be placed on factory methods that are to be added to prototype, first parameter is the prototype instance                                                                                      |
-| `RuntimeType.PrototypedBy`  | `true`   | Annotation on runtime type that is created from a `Prototype`, to map it to the prototype it can be created from, used to trigger annotation processor for validation                                        |
+| Annotation                           | Required | Description                                                                                                                                                        |
+|--------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Prototype.Blueprint`                | `true`   | Annotation on the blueprint interface is required to trigger annotation processing                                                                                 |
+| `Prototype.Implement`                | `false`  | Add additional implemented types to the generated prototype                                                                                                        |
+| `Prototype.Annotated`                | `false`  | Allows adding an annotation (or annotations) to the generated class or methods                                                                                     |
+| ~~`Prototype.FactoryMethod`~~        | `false`  | Deprecated and marked for removal                                                                                                                                  |
+| `Prototype.PrototypeFactoryMethod`   | `false`  | Annotates a method in a `CustomMethods` type to be added as a static method to the prototype                                                                       |
+| `Prototype.ConfigFactoryMethod`      | `false`  | Annotates a method in a `CustomMethods` type that creates an option from `Config` on a configured type                                                             |
+| `Prototype.RuntimeTypeFactoryMethod` | `false`  | Annotates a method in a `CustomMethods` type that creates an option runtime type from its prototype (the parameter must be another prototype                       |
+| `Prototype.Singular`                 | `false`  | Used for lists, sets, and maps to add methods `add*`/`put*` in addition to the full collection setters                                                             |     
+| `Prototype.SameGeneric`              | `false`  | Use for maps, where we want a setter method to use the same generic type for key and for value (such as `Class<T> key, T valuel`)                                  |
+| `Prototype.Redundant`                | `false`  | A redundant option will not be part of generated `toString`, `hashCode`, and `equals` methods (allows finer grained control)                                       |
+| `Prototype.Confidential`             | `false`  | A confidential option will not have value visible when `toString` is called, only if it is `null` or it has a value (`****`)                                       |
+| `Prototype.CustomMethods`            | `false`  | reference a class that will contain declarations (all static) of custom methods to be added to the generated code, can add prototype, builder, and factory methods |
+| `Prototype.BuilderMethod`            | `false`  | Annotation to be placed on factory methods that are to be added to builder, first parameter is the `BuilderBase<?, ?>` of the prototype                            |
+| `Prototype.PrototypeMethod`          | `false`  | Annotation to be placed on factory methods that are to be added to prototype, first parameter is the prototype instance                                            |
+| ~~`RuntimeType.PrototypedBy`~~       | `true`   | Deprecated and marked for removal                                                                                                                                  |
 
 Interfaces:
 

builder/api/src/main/java/io/helidon/builder/api/Prototype.java

@@ -18,6 +18,7 @@
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Inherited;
+import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
@@ -143,6 +144,8 @@ public interface Factory<T> {
          * Whether to use bean style setters and getters, or not (default is not).
          * If set to {@code true}, only methods starting with {@code get} would be used,
          * and all setters will start with {@code set}, except for add methods.
+         * <p>
+         * NOTE: bean style must be consistent in a hierarchy, otherwise we cannot discover properties correctly.
          *
          * @return whether to use bean style accessors, defaults to false
          */
@@ -157,6 +160,13 @@ public interface Factory<T> {
          * @return decorator type
          */
         Class<? extends BuilderDecorator> decorator() default BuilderDecorator.class;
+
+        /**
+         * If set to {@code true} the generated type will not extend the blueprint interface.
+         *
+         * @return whether to detach the generated type from the blueprint interface
+         */
+        boolean detach() default false;
     }
 
     /**
@@ -248,36 +258,35 @@ public interface OptionDecorator<B, T> {
         /**
          * Decorate a list of values, when a setter that replaces values is called.
          *
-         * @param builder       the target builder being decorated
-         * @param optionValues  option values set by the caller of the setter method
+         * @param builder      the target builder being decorated
+         * @param optionValues option values set by the caller of the setter method
          */
         default void decorateSetList(B builder, List<T> optionValues) {
         }
 
         /**
          * Decorate a list of values, when a setter that adds values is called.
          *
-         * @param builder       the target builder being decorated
-         * @param optionValues  option values set by the caller of the setter method
+         * @param builder      the target builder being decorated
+         * @param optionValues option values set by the caller of the setter method
          */
         default void decorateAddList(B builder, List<T> optionValues) {
         }
 
         /**
          * Decorate a set of values, when a setter that replaces values is called.
          *
-         * @param builder       the target builder being decorated
-         * @param optionValues  option values set by the caller of the setter method
+         * @param builder      the target builder being decorated
+         * @param optionValues option values set by the caller of the setter method
          */
         default void decorateSetSet(B builder, Set<T> optionValues) {
         }
 
-
         /**
          * Decorate a set of values, when a setter that adds values is called.
          *
-         * @param builder       the target builder being decorated
-         * @param optionValues  option values set by the caller of the setter method
+         * @param builder      the target builder being decorated
+         * @param optionValues option values set by the caller of the setter method
          */
         default void decorateAddSet(B builder, Set<T> optionValues) {
         }
@@ -301,9 +310,7 @@ default void decorateAddSet(B builder, Set<T> optionValues) {
     }
 
     /**
-     * This is an annotation used by Helidon code generator that marks a static method
-     * as a factory method.
-     * <p>
+     * Old behavior, kept for backward compatibility:
      * This annotation must be defined on any static method that should be used as a factory for runtime types from
      * prototypes, and from configuration on {@link Prototype.Blueprint}.
      * <p>
@@ -317,15 +324,103 @@ default void decorateAddSet(B builder, Set<T> optionValues) {
      *          prototype from configuration</li>
      *     <li>{@code static Prototype create()} - a method that creates a new instance if there are no required fields</li>
      * </ul>
-     * This annotation is also used for triggering an additional round of annotation processing by the generated types, to
-     * finalize
-     * validation.
+     *
+     * @deprecated use {@link io.helidon.builder.api.Prototype.PrototypeFactoryMethod},
+     *         {@link io.helidon.builder.api.Prototype.ConfigFactoryMethod},
+     *         or {@link io.helidon.builder.api.Prototype.RuntimeTypeFactoryMethod} for other types this annotation
+     *         could have been used for in the past
      */
     @Target({ElementType.METHOD, ElementType.TYPE})
     @Retention(RetentionPolicy.CLASS)
+    @Deprecated(forRemoval = true, since = "4.4.0")
     public @interface FactoryMethod {
     }
 
+    /**
+     * Factory method that is added to the generated prototype.
+     * <p>
+     * This annotation MUST be on a static method that is part of a type referenced from blueprint through
+     * {@link io.helidon.builder.api.Prototype.CustomMethods}.
+     */
+    @Target(ElementType.METHOD)
+    @Retention(RetentionPolicy.CLASS)
+    public @interface PrototypeFactoryMethod {
+    }
+
+    /**
+     * Factory method that creates an option from a config instance.
+     * The config (the only parameter) must be of type {@code io.helidon.config.Config}.
+     * <p>
+     * The return type of the method must match the type of the option.
+     * <p>
+     * This annotation MUST be on a static method that is part of a type referenced from blueprint through
+     * {@link io.helidon.builder.api.Prototype.CustomMethods}.
+     */
+    @Target(ElementType.METHOD)
+    @Retention(RetentionPolicy.CLASS)
+    public @interface ConfigFactoryMethod {
+        /**
+         * An explicit option name can be defined to only use this factory method for the specified option.
+         * If none is specified, the factory method will be used for all options of the matching type.
+         *
+         * @return option name
+         */
+        String value() default "";
+    }
+
+    /**
+     * Factory method that creates an option from a prototype instance.
+     * The prototype (the only parameter) must be a type that has {@code builder} method that returns a builder,
+     * that can be built using {@code build} method (method names are customizable).
+     * <p>
+     * The return type of the method must match the type of the option.
+     * <p>
+     * This annotation MUST be on a static method that is part of a type referenced from blueprint through
+     * {@link io.helidon.builder.api.Prototype.CustomMethods}.
+     */
+    @Target(ElementType.METHOD)
+    @Retention(RetentionPolicy.CLASS)
+    public @interface RuntimeTypeFactoryMethod {
+        /**
+         * An explicit option name can be defined to only use this factory method for the specified option.
+         * If none is specified, the factory method will be used for all options of the matching type.
+         *
+         * @return option name
+         */
+        String value() default "";
+
+        /**
+         * Name of the builder method on the prototype.
+         * If set to {@code <init>}, the builder will be created through its constructor, in such a case
+         * {@link #builderType()} must be provided as well.
+         *
+         * @return builder method name, defaults to {@code builder} if not set
+         */
+        String builderMethodName() default "builder";
+
+        /**
+         * Name of the build method on the builder to create an instance of the desired type.
+         *
+         * @return build method name, defaults to {@code build} if not set
+         */
+        String buildMethodName() default "build";
+
+        /**
+         * Type of the builder to use when creating the prototype instance.
+         *
+         * @return type of the builder, defaults to the type returned by the {@link #builderMethodName()}
+         */
+        Class<?> builderType() default RuntimeTypeFactoryMethod.class;
+
+        /**
+         * Type of the class declaring a {@link #builderMethodName()} used to get an instance of the builder to send
+         * to the generated setter with consumer.
+         *
+         * @return type declaring the builder method
+         */
+        Class<?> builderMethodType() default RuntimeTypeFactoryMethod.class;
+    }
+
     /**
      * Additional methods from this type will be added to the prototype and its builder.
      * All methods must be declared as static.
@@ -446,5 +541,36 @@ default void decorateAddSet(B builder, Set<T> optionValues) {
         String[] value() default {};
     }
 
+    /**
+     * Extension definition for a blueprint.
+     * Extensions allow modification of the generated code that is outside the scope of the default builder codegen.
+     * This can be used, for example, to generate {@code JSON} binding annotations.
+     */
+    @Target(ElementType.TYPE)
+    @Retention(RetentionPolicy.CLASS)
+    @Repeatable(Extensions.class)
+    public @interface Extension {
+        /**
+         * Type the extension supports, see documentation of appropriate extension.
+         *
+         * @return type the extension supports
+         */
+        Class<?> value();
+    }
+
+    /**
+     * Container of {@link io.helidon.builder.api.Prototype.Extension} annotations, to allow more than one extension to be
+     * used.
+     */
+    @Target(ElementType.TYPE)
+    @Retention(RetentionPolicy.CLASS)
+    public @interface Extensions {
+        /**
+         * Extensions to use.
+         *
+         * @return extensions to use
+         */
+        Extension[] value();
+    }
 }
 

builder/api/src/main/java/io/helidon/builder/api/RuntimeType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023 Oracle and/or its affiliates.
+ * Copyright (c) 2023, 2025 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -42,16 +42,15 @@ public interface Api<T extends Prototype.Api> {
         T prototype();
     }
 
-
     /**
-     * Mark this runtime type as prototyped by a specific prototype.
-     * The prototype is generated through {@link io.helidon.builder.api.Prototype.Blueprint} definition.
-     * <p>
-     * This is complementing {@link RuntimeType} interface.
-     * We need to have both the annotation and implement the interface, to correctly validate the object tree.
+     * This annotation is no longer used.
+     *
+     * @deprecated this is an unnecessary duplication of what is required on the blueprint, use only blueprint
+     * {@link io.helidon.builder.api.Prototype.Factory} instead.
      */
     @Target(ElementType.TYPE)
     @Retention(RetentionPolicy.CLASS)
+    @Deprecated(forRemoval = true, since = "4.4.0")
     public @interface PrototypedBy {
         /**
          * Type of the prototype.