New config builders (helidon-io#7008)

* Plugin version updates
* Builder API changes and associated changes to common project
* Pico changes (config driven, new builder APIs)
* Config changes (new builder API, metadadata updates)
* Changes required after changes to common modules and builders
* Nima changes
* BOM POM
* Tests update
* Examples
* Integration test fixes (and related fixes in production code).
* Make sure we do not require transitive dependency on Config for Builder.
* Archetype fix

Author: tomas-langer

archetypes/helidon/src/main/archetype/nima/common/files/src/main/java/__pkg__/Main.java.mustache

@@ -37,6 +37,7 @@ public final class Main {
 
         WebServer server = WebServer.builder()
                 .routing(Main::routing)
+                .build()
                 .start();
 
         System.out.println("WEB server is up! http://localhost:" + server.port() + "/greet");

bom/pom.xml

@@ -681,6 +681,16 @@
                 <artifactId>helidon-common-types</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.helidon.common.processor</groupId>
+                <artifactId>helidon-common-processor</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.helidon.common.processor</groupId>
+                <artifactId>helidon-common-processor-helidon-copyright</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
             <dependency>
                 <groupId>io.helidon.common.testing</groupId>
                 <artifactId>helidon-common-testing-junit5</artifactId>
@@ -1395,6 +1405,11 @@
                 <artifactId>helidon-nima-fault-tolerance</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.helidon.nima.fault-tolerance</groupId>
+                <artifactId>helidon-nima-fault-tolerance-processor</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
             <dependency>
                 <groupId>io.helidon.nima.openapi</groupId>
                 <artifactId>helidon-nima-openapi</artifactId>
@@ -1404,39 +1419,14 @@
             <!-- Builder -->
             <dependency>
                 <groupId>io.helidon.builder</groupId>
-                <artifactId>helidon-builder</artifactId>
-                <version>${helidon.version}</version>
-            </dependency>
-            <dependency>
-                <groupId>io.helidon.builder</groupId>
-                <artifactId>helidon-builder-processor-spi</artifactId>
-                <version>${helidon.version}</version>
-            </dependency>
-            <dependency>
-                <groupId>io.helidon.builder</groupId>
-                <artifactId>helidon-builder-processor-tools</artifactId>
+                <artifactId>helidon-builder-api</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
             <dependency>
                 <groupId>io.helidon.builder</groupId>
                 <artifactId>helidon-builder-processor</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
-            <dependency>
-                <groupId>io.helidon.builder</groupId>
-                <artifactId>helidon-builder-config</artifactId>
-                <version>${helidon.version}</version>
-            </dependency>
-            <dependency>
-                <groupId>io.helidon.builder</groupId>
-                <artifactId>helidon-builder-config-processor</artifactId>
-                <version>${helidon.version}</version>
-            </dependency>
-            <dependency>
-                <groupId>io.helidon.builder</groupId>
-                <artifactId>helidon-builder-testing</artifactId>
-                <version>${helidon.version}</version>
-            </dependency>
 
             <!-- Pico Core -->
             <dependency>

builder/README.md

@@ -1,44 +1,49 @@
-# builder
+# Helidon Builder
 
-The <b>Helidon Builder</b> provides compile-time code generation for fluent builders. It was inspired by [Lombok]([https://projectlombok.org/), but the implementation here in Helidon is different in a few ways:
-<ol>
-    <li>The <i>Builder</i> annotation targets interface or annotation types only. Your interface effectively contains the attributes of your getter as well as serving as the contract for your getter methods.</li>
-    <li>Generated classes implement your target interface (or annotation or abstract class) and provide a fluent builder that will always have an implementation of <i>toString(), hashCode(), and equals().</i> implemented</li>
-    <li>Generated classes always behave like a <i>SuperBuilder</i> from Lombok. Basically this means that builders can form
-      a hierarchy on the types they target (e.g., Level2 derives from Level1 derives from Level0, etc.).</li>
-    <li>Lombok uses AOP while the Helidon Builder generates source code. You can use the <i>Builder</i> annotation (as well as other annotations in the package and <i>ConfiguredOption</i>) to control the naming and other features of what and how the implementation classes are generated and behave.</li>
-    <li>Builders are extensible - you can provide your own implementation of the <b>Builder Processor SPI</b> to customize the generated classes for your situation.</li>
-</ol>
+This module is used by Helidon to generate types with builders (Prototypes) to be used in API of modules from a blueprint interface.
 
-Supported annotation types (see [builder](./builder/src/main/java/io/helidon/builder) for further details):
-* Builder - similar to Lombok's SuperBuilder.
-* Singular - similar to Lombok's Singular.
-* NonNull - accomplished alternatively via Helidon's <i>ConfiguredOption#required</i>.
-* Default - accomplished alternatively via Helidon's <i>ConfiguredOption#value</i>.
+There are two modules that are used:
+- `helidon-builder-api` - module required in `compile` scope, contains annotations and APIs needed to write blueprints, and to build the generated code
+- `helidon-builder-processor` - module to be placed on annotation processor path, generates the sources
 
-Explicitly unsupported (i.e., these are just a few of the types that do not have a counterpart from Helidon's Builder):
-* NoArgsConstructor - must instead use one of the <i>toBuilder()</i> methods
-* AllArgsConstructor - must instead use one of the <i>toBuilder()</i> methods
+There is one module useful for internal development
+- `helidon-builder-tests-common-types` (located under `tests/common-types`) that contains blueprints for the types we use in `helidon-common-types`. As the common types module is used by the processor, we would end up with a cyclic dependency, so this allows us to generate the next iteration of common types (requires manual copying of the generated types)
 
-Any and all types are supported by the Builder, with special handling for List, Map, Set, and Optional types. The target interface,
-however, should only contain getter like methods (i.e., has a non-void return and takes no arguments). All static and default methods
-are ignored on the target being processed.
+## Goals
 
-The Helidon Builder is independent of other parts of Helidon. It can therefore be used in a standalone manner. The
-generated implementation class will not require any special module to support those classes - just the types from your interface
-and standard JRE types are used. This is made possible when your <i>Builder</i> has the <i>requireBuilderLibrary=false</i>. See the javadoc for details.
+Generate all required types for Helidon APIs with builders, that follow the same style (method names, required validation etc.).
+
+The following list of features is currently supported:
+- `Builder` also implements the interface of the type (all getters are available also on builder) 
+- `Type` options - interface returns `Type`, such an option MUST NOT be null in the built instance, there is a validation in place on calling the `build` or `buildPrototype` methods. Getters MAY return null on a builder
+- `Optional` options - interface returns `Optional<Type>`, setters use just `Type`, there is a package local setter that accepts `Optional` as well, to support updating a builder from an existing instance
+- `List` options - interface returns `List<Type>`, never null - if there is no configured value, empty string is returned
+- `Set` options - similar to list
+- `Map` options - key/value map, builders support any key/value types, but if configuration is used, the key must be a string
+- "Singular" for collection based options, which adds setter for a single value (for `List<String> algorithms()`, there would be the following setters: `algorithms(List<String>)`, `addAlgorithms(List<String>)`, `addAlgorithm(String)`)
+- A type can be `@Configured`, which adds integration with Helidon common Config module, by adding a static factory method `create(io.helidon.common.Config)` to the generated type, as well as `config(Config)` method to the generated builder, that sets all options annotated with `@ConfiguredOption` from configuration (if present in the Config instance)
+- Capability to update the builder before validation (interceptor)
+- Support for custom methods (`@Prototype.CustomMethods`) for factory methods, prototype methods, and builder methods
+
+## Non-Goals
+
+We are not building a general purpose solution, there are limitations that are known and will not be targetted:
+- the solution expects that everything is single package - blueprints are required to be package local, which does not allow using built types across packages within a single module
+- we only support interface based definition of blueprints (no classes)
+- we only support non-nullable options, instead of nullable, use `Optional` getters
+- implementation types of collections are fixed to `java.util.ArrayList`, `java.util.LinkedHashSet` and `java.util.LinkedHashMap`
 
 ## Getting Started
 1. Write your interface that you want to have a builder for.
 ```java
-public interface MyConfigBean {
+interface MyConfigBeanBlueprint {
     String getName();
     boolean isEnabled();
     int getPort();
 }
 ```
-2. Annotate your interface definition with <i>Builder</i>, and optionally use <i>ConfiguredOption</i>, <i>Singular</i>, etc. Remember to review the annotation attributes javadoc for any customizations.
-3. Builder (using the <i>builder-processor</i> in your annotation classpath).
+2. Annotate your interface definition with `@Blueprint`, and optionally use `@ConfiguredOption`, `Singular` etc. to customize the getter methods. Remember to review the annotation attributes javadoc for any customizations.
+3. Update your pom file to add annotation processor
 ```xml
     ...
     <build>
@@ -48,13 +53,6 @@ public interface MyConfigBean {
                 <artifactId>maven-compiler-plugin</artifactId>
                 <configuration>
                     <annotationProcessorPaths>
-                        <!-- this path is needed if only requiring the Builder annotation -->
-                        <path>
-                            <groupId>io.helidon.builder</groupId>
-                            <artifactId>helidon-builder-processor</artifactId>
-                            <version>${helidon.version}</version>
-                        </path>
-                        <!-- this path is needed if requiring the ConfigBean annotation (which will automatically bring in the Builder processor transitively) -->
                         <path>
                             <groupId>io.helidon.builder</groupId>
                             <artifactId>helidon-builder-processor</artifactId>
@@ -68,37 +66,10 @@ public interface MyConfigBean {
     ...
 ```
 
-The result of this will create (under ./target/generated-sources/annotations):
-* MyConfigBeanImpl (in the same package as MyConfigBean) that will support multi-inheritance builders named MyConfigBeanImpl.Builder.
-* Support for toString(), hashCode(), and equals() are always included.
-* Support for toBuilder().
-* Support for streams (see javadoc for [Builder](./builder/src/main/java/io/helidon/builder/Builder.java)).
-* Support for attribute visitors (see [test-builder](./tests/builder/src/main/java/io/helidon/builder/test/testsubjects/package-info.java)).
-* Support for attribute validation (see ConfiguredOption#required() and [test-builder](./tests/builder/src/main/java/io/helidon/builder/test/testsubjects/package-info.java)).
-* Support for builder interception (i.e., including decoration or mutation). (see [test-builder](./tests/builder/src/main/java/io/helidon/builder/test/testsubjects/package-info.java)).
-
-Also note that the generated code from Helidon Builder processors may add other dependencies that you will need to add (typically in <i>provided</i> scope).
-```xml
-    <dependency>
-        <groupId>jakarta.annotation</groupId>
-        <artifactId>jakarta.annotation-api</artifactId>
-        <scope>provided</scope>
-        <optional>true</optional>
-    </dependency>
-```
-
-## Modules
-* [builder](./builder) - provides the compile-time annotations, as well as optional runtime supporting types.
-* [processor-spi](./processor-spi) - defines the Builder Processor SPI runtime definitions used by builder tooling. This module is only needed at compile time.
-* [processor-tools](./processor-tools) - provides the concrete creators & code generators. This module is only needed at compile time.
-* [processor](./processor) - the annotation processor which delegates to the processor-tools module for the main processing logic. This module is only needed at compile time.
-* [builder-config](./builder-config) - extension to the builder to additionally support [Helidon (Common) Config](../common/config) and [@ConfigBean](./builder-config/src/main/java/io/helidon/builder/config/ConfigBean.java).
-* [builder-config-processor](./builder-config-processor) - defines the ConfigBean builder.
-* [tests](./tests) - tests that can also serve as examples for usage.
-
-## Customizations and Extensibility
-To implement your own custom <i>Builder</i>:
-* See [builder-config](../builder-config) serving as an example.
-
-## Usage
-See [tests/builder](./tests/builder) for usage examples.
+Generated types will be available under `./target/generated-sources/annotations`
+* MyConfigBean (in the same package as MyConfigBeanBlueprint), with inner classes `BuilderBase` (for inheritance), `Builder`,
+* Support for `toString()`, `hashCode()`, and `equals()` are always included.
+* Support for `builder(MyConfigBean)` to create a new builder from an existing instance
+* Support for `from(MyConfigBean)` and `from(MyConfigBean.BuilderBase<?, ?>)` to update builder from an instance or builder
+* Support for validation of required and non-nullable options (required options are options that have `@ConfiguredOption(required=true)`, non-nullable option is any option that is not primitive, collection, and does not return an `Optional`)
+* Support for builder interception (`@Bluprint(builderInterceptor = MyInterceptor.class)`)