• Blueprint: A package-private interface that serves as the source for code generation.

• Prototyped: The generated code extending the blueprint. It is part of the public API and includes the fluent builder implementation and static factory methods.

• Runtime Type: An optional, user-defined type created using the prototype. It is useful for constructing custom objects beyond the generated prototype.

Here’s a simple example of a blueprint:

@Prototype.Blueprint
interface ServiceConfigBlueprint {
    String name();
    int pageSize();
}

The generated prototype can be used as follows:

ServiceConfig serviceConfig = ServiceConfig.builder()
    .name("My Service")
    .pageSize(10)
    .build();

• Reflection-free implementation; no bytecode manipulation.

• Support for inheritance in prototypes and blueprints.

• Automatic Javadoc generation.

• Seamless integration with Helidon Config for property initialization, default values, and advanced customization.

• Optional generation of factory, prototype, and builder methods.

• Supports List, Set, and Map collections.

• Explicit default value support for common types (String, int, long, boolean, etc.).

• Enumeration support.

• Prototypes are generated in the same package as their blueprints.

• Blueprints must be package-private interfaces.

• Classes are not supported as blueprints.

• null values are not allowed; use Optional instead.

• Collection types are fixed to ArrayList, LinkedHashSet, and LinkedHashMap.

This use case demonstrates generating an immutable class with a builder from a blueprint interface. The blueprint serves as the input for code generation, and the resulting prototype provides a fluent API for constructing instances.

1. Blueprint Requirements:

   • Must be a package-private interface.

   • Its name must end with Blueprint. The prototype’s name will be the blueprint’s name without this suffix.

   • Options are defined as getter methods.

2. Generated Output:

   • Prototype is a part of your module public API.

   • The prototype class is placed in the same package as the blueprint.

   • Generated files can be found in the ./target/generated-sources/annotations directory.

This example demonstrates generating a prototype from the blueprint below.

@Prototype.Blueprint                   
interface ServiceConfigBlueprint {     
    String name();                     
    int pageSize();
}

• Marks the interface as a blueprint for code generation.
• Must be package-private and named with a Blueprint suffix. The prototype’s name will be ServiceConfig.
• Getter method for field name.

After building the project, a prototype ServiceConfig will be generated.

Example of the generated prototype:

@Generated(value = "io.helidon.builder.codegen.BuilderCodegen",
           trigger = "com.example.ServiceConfigBlueprint")                           
public interface ServiceConfig extends ServiceConfigBlueprint, Prototype.Api {       
    static ServiceConfig.Builder builder() { /* ... */ }                             

    static ServiceConfig.Builder builder(ServiceConfig instance) { /* ... */ }       

    static ServiceConfig create() { /* ... */ }                                      

    class Builder extends ServiceConfig.BuilderBase<ServiceConfig.Builder, ServiceConfig>
        implements io.helidon.common.Builder<ServiceConfig.Builder, ServiceConfig> { 
        // ...
    }

    // ...
}

• Marker annotation specifying that this interface was generated.
• Generated interface extending the given blueprint. The interface name is a blueprint name with "Blueprint" suffix removed.
• Static method returning a generated builder.
• Static method returning a generated builder initialized with the field value from given instance.
• Factory method creating an instance with default values.
• Generated builder.

The generated ServiceConfig can be used as follows:

ServiceConfig serviceConfig = ServiceConfig.builder()
    .name("My Service")
    .pageSize(10)
    .build();

This ensures type safety, immutability, and a fluent API for constructing objects.

This scenario extends the basic builder functionality by enabling the generated prototype to initialize its fields using values from Helidon Config.

1. The blueprint must be annotated with @Prototype.Configured to enable configuration-based initialization.
2. Each field initialized from the configuration must be annotated with @Option.Configured.
3. Default values can be set using @Option.Default. If a configuration value is missing, the default is used.
4. null values are not supported; use Optional for optional fields.
5. Lists, Sets, and Maps are supported and initialized from configuration.
6. You can customize and validate fields using the @Option API. Advanced programmatic customization is possible by implementing a custom BuilderDecorator via @Prototype.Blueprint(decorator = MyDecorator.class).

The following example demonstrates how to configure a ServiceConfig object using Helidon Config.

Blueprint Definition:

@Prototype.Blueprint
@Prototype.Configured("service")      
interface ServiceConfigBlueprint {
    @Option.Configured                
    String name();

    @Option.Configured
    @Option.DefaultInt(50)            
    int pageSize();
}

• Specifies that this blueprint can be configured with the root key service in the configuration.
• Marks the field name as configurable. By default, the configuration key is derived from the method name in dash-separated format.
• Sets a default value for pageSize if it is not defined in the configuration.

The generated prototype includes a create method that accepts a Config instance:

static ServiceConfig create(Config config);

Usage:

Config config = Config.create();
ServiceConfig serviceConfig = ServiceConfig.create(config);

Example configuration in application.properties file:

service.name=My Service
service.page-size=10

Helidon Builder supports a range of customization options:

• Field Validation: Add constraints or validations using annotations like @Option.AllowedValues or @Option.Required.

• Field Transformation: Use a custom BuilderDecorator to modify field values during the build process.

For additional customization details, see the API section.

This scenario extends the basic functionality of Helidon Builder to create a user-defined runtime type based on a prototype. This approach is particularly useful when the generated prototype needs to be transformed into a domain-specific runtime type.

To enable runtime object creation, follow these guidelines:

1. Prototype Factory:
   The blueprint must extend Prototype.Factory<RuntimeType>, where RuntimeType is the desired runtime type.
2. This option has been removed, as it is redundant (@PrototypedBy), this annotation is deprecated and will be eventually removed; it has no function now
3. Runtime Type Interface:
   The runtime type must implement RuntimeType.Api<Prototype> to indicate the prototype it is based on.
4. Required Methods in Runtime Type:
   The runtime type must include the following methods, implemented by the user:

   • public static Prototype.Builder builder()
     Provides a builder for the runtime type.

   • public static RuntimeType create(Prototype)
     Creates a runtime type from a prototype instance.

   • public static RuntimeType create(Consumer<Prototype.Builder>)
     Creates a runtime type from a consumer to configure the prototype builder.

5. Prototype Integration:
   The blueprint must include the @Prototype.Blueprint annotation and extend Prototype.Factory<RuntimeType>.

Note that requirements 3 - 5 can be omitted when using a third party runtime type (i.e. PrivateKey), in such a case the setup should be:

1. Create a blueprint that extends Prototype.Factory<RuntimeType> (same as above)
2. Add a custom method annotated with @Prototype.RuntimeTypeFactoryMethod (custom methods can be configured on blueprint using @Prototype.CustomMethods, the custom method is a static method with signature RuntimeType create(Prototype)), method name is arbitrary

This will generate a prototype that has a method build() that builds the RuntimeType.

The following example demonstrates creating a Service runtime type from a ServiceConfigBlueprint.

Runtime type implementation:

public class Service implements RuntimeType.Api<ServiceConfig> {             
    public static ServiceConfig.Builder builder() {                          
        return ServiceConfig.builder();
    }

    public static Service create(ServiceConfig serviceConfig) {              
        rreturn new ServiceImpl(serviceConfig);
    }

    public static Service create(Consumer<ServiceConfig.Builder> consumer) { 
        return builder().update(consumer).build();
    }
}

• Implements the RuntimeType.Api<ServiceConfig> interface.
• Provides a builder for the runtime type.
• Creates a runtime object from a prototype.
• Creates a runtime object from a consumer-configured prototype builder.

Blueprint definition:

@Prototype.Blueprint
@Prototype.Configured("service")
interface ServiceConfigBlueprint extends Prototype.Factory<Service> { 
    @Option.Configured
    String name();

    @Option.Configured
    @Option.DefaultInt(50)
    int pageSize();
}

• Extending Prototype.Factory<Service> enables creating Service runtime objects.

Usage:

• Using a fluent builder:

  Service service = Service.builder().build();

  content_copy Copied

• Using intermediate prototype object:

  ServiceConfig serviceConfig = ServiceConfig.builder().buildPrototype();
  Service service = serviceConfig.build();

  content_copy Copied

• Using a consumer to configure the builder:

  Service service = Service.create(builder -> builder.name("My Service")
                                                     .pageSize(10));

  content_copy Copied

Annotations:

Interfaces:

To configure default value(s) of an option, one of the following annotations can be used (mutually exclusive!). Most defaults support an array, to provide default values for collections.