Module io.helidon.builder
Package io.helidon.builder

Annotation Interface Builder

@Target(TYPE) @Retention(CLASS) @BuilderTrigger public @interface Builder
Adding this annotation on an interface will cause the Builder's annotation processor to generate an implementation of the interface that supports the builder pattern.

Supplemental annotation types that are supported in conjunction with this builder type include:

  • Annotated - in order to add custom annotations on the implementation.
  • Singular - when using lists, maps, and sets on getter methods.
  • io.helidon.config.metadata.ConfiguredOption - for handling default values, policy constraints, etc.
See Also:

  • Field Details

    • DEFAULT_IMPL_PREFIX

      static final String DEFAULT_IMPL_PREFIX
      The default prefix appended to the generated class name.
      See Also:

    • DEFAULT_ABSTRACT_IMPL_PREFIX

      static final String DEFAULT_ABSTRACT_IMPL_PREFIX
      The default prefix appended to the generated abstract class name (the parent for the DEFAULT_IMPL_PREFIX).
      See Also:

    • DEFAULT_SUFFIX

      static final String DEFAULT_SUFFIX
      The default suffix appended to the generated class name(s).
      See Also:

    • DEFAULT_ALLOW_NULLS

      static final boolean DEFAULT_ALLOW_NULLS
      The default value for allowNulls().
      See Also:

    • DEFAULT_INCLUDE_GENERATED_ANNOTATION

      static final boolean DEFAULT_INCLUDE_GENERATED_ANNOTATION
      The default value for includeGeneratedAnnotation().
      See Also:

    • DEFAULT_DEFINE_DEFAULT_METHODS

      static final boolean DEFAULT_DEFINE_DEFAULT_METHODS
      The default value for defineDefaultMethods().
      See Also:

    • DEFAULT_LIST_TYPE

      static final Class<? extends List> DEFAULT_LIST_TYPE
      The default list type used for the generated class implementation for any references to List is found on the methods of the Builder-annotation interface.

    • DEFAULT_MAP_TYPE

      static final Class<? extends Map> DEFAULT_MAP_TYPE
      The default map type used for the generated class implementation for any references to Map is found on the methods of the Builder-annotation interface.

    • DEFAULT_SET_TYPE

      static final Class<? extends Set> DEFAULT_SET_TYPE
      The default set type used for the generated class implementation for any references to Set is found on the methods of the Builder-annotation interface.

  • Element Details

    • packageName

      String packageName
      The package name to use for the generated class. If the package name starts with "." then the package name will be relative to the target type. If left undefined (i.e., an empty string) it will default to the target type's package name.
      Returns:
      the package name to use for the generated class
      Default:
      ""

    • implPrefix

      String implPrefix
      The prefix name that will be assigned to the implementation class that is code generated. Default is DEFAULT_IMPL_PREFIX.

      Note also that if your application uses a super builder inheritance scheme (i.e., A extends B extends C) then it is expected that all the Builder annotations for this attribute is set uniformly to the same value.

      Returns:
      the prefix name
      Default:
      "Default"

    • abstractImplPrefix

      String abstractImplPrefix
      The prefix name that will be assigned to the abstract implementation class that is code generated. Default is DEFAULT_ABSTRACT_IMPL_PREFIX.

      Note also that if your application uses a super builder inheritance scheme (i.e., A extends B extends C) then it is expected that all the Builder annotations for this attribute is set uniformly to the same value.

      Returns:
      the prefix name
      Default:
      "Abstract"

    • implSuffix

      String implSuffix
      The suffix name that will be assigned to the implementation class that is code generated. Default is DEFAULT_SUFFIX.

      Note also that if your application uses a super builder inheritance scheme (i.e., A extends B extends C) then it is expected that all the Builder annotations for this attribute is set uniformly to the same value.

      Returns:
      the suffix name
      Default:
      ""

    • requireLibraryDependencies

      boolean requireLibraryDependencies
      Should the code-generated source(s) require a runtime dependency on Helidon libraries? The default is true.

      When set to true, the generated Builder class will rely on common libraries from Helidon as the basis for Builder, AttributeVisitor, etc. This would therefore require your consumer application to have a compile/runtime dependency on the builder/runtime-tools module (having an additional transitive dependency on common/common.

      When set to false, the generated source(s) will self-contain all the supporting types, and thereby avoids any dependencies on any extra Helidon libraries. The cost, however, is code duplication since each builder generated will replicate these types.

      Note also that if your application uses a super builder inheritance scheme (i.e., A extends B extends C) then it is expected that all the Builder annotations for this attribute is set uniformly to the same value.

      Returns:
      true to extend and use supporting libraries to avoid duplication of generated types
      Default:
      true

    • includeMetaAttributes

      boolean includeMetaAttributes
      Should the code-generates source(s) be capable of providing meta-related extensions. This includes, but is not limited to, the following:
      • access to attribute names, types, and ConfigurationOption attributes in a map-like structure - avoiding runtime reflection
      • providing attribute visitor and visitation capabilities
      • providing ConfigurationOption#required=true validation (based upon the above visitors)
      The default is true. Note also that in some (future) scenarios, Helidon will mandate this attribute be enabled.

      Note also that if your application uses a super builder inheritance scheme (i.e., A extends B extends C) then it is expected that all the Builder annotations for this attribute is set uniformly to the same value.

      Returns:
      true to support meta-related attributes and extensions
      Default:
      true

    • requireBeanStyle

      boolean requireBeanStyle
      Should bean style be enforced. Set to true to force the use of isX() (for booleans) or getY() (for non booleans) on the target type's methods. Default is false. When enabled then any violation of this will lead to a compile-time error by the Builder's annotation processor. Default is false.
      Returns:
      true to enforce bean style
      Default:
      false

    • allowNulls

      boolean allowNulls
      Should the bean and the builder allow for the possibility of nullable non-Optional values to be present. Default is false.
      Returns:
      true to allow for the possibility of nullable non-Optional values to be present
      Default:
      false

    • includeGeneratedAnnotation

      boolean includeGeneratedAnnotation
      Should the code generated types included the Generated annotation. Including this annotation will require an additional module dependency on your modules to include jakarta.annotation-api.
      Returns:
      true to include the Generated annotation
      Default:
      true

    • defineDefaultMethods

      boolean defineDefaultMethods
      Default methods are normally skipped. Setting this to true will allow definition for all default methods from the target type, but only for getter-type methods taking no arguments.
      Returns:
      true to define default methods
      Default:
      false

    • interceptor

      Class<?> interceptor
      The interceptor implementation type. See BuilderInterceptor for further details. Any interceptor applied will be called prior to validation. The interceptor implementation can be any lambda-like implementation for the BuilderInterceptor functional interface. This means that the implementation should declare a public method that matches the following: 
      
    Builder intercept(Builder builder);
      Note that the method name must be named intercept.
      Returns:
      the interceptor implementation class
      Default:
      java.lang.Void.class

    • interceptorCreateMethod

      String interceptorCreateMethod
      The (static) interceptor method to call on the interceptor() implementation type in order to create the interceptor. If left undefined then the new operator will be called on the type. If provided then the method must be public and take no arguments. Example (see the create() method): 
      
  public class CustomBuilderInterceptor { // implements BuilderInterceptor
      public CustomBuilderInterceptor() {
      }

      public static CustomBuilderInterceptor create() {
          ...
      }

      public Builder intercept(Builder builder) {
          ...
      }
  }

      This attribute is ignored if the interceptor() class type is left undefined. Note that the method must return an instance of the Builder, and there must be a public method that matches the following: 

      
    public Builder intercept(Builder builder);
      Note that the method name must be named intercept.
      Returns:
      the interceptor create method
      Default:
      ""

    • listImplType

      Class<? extends List> listImplType
      The list implementation type to apply, defaulting to DEFAULT_LIST_TYPE.
      Returns:
      the list type to apply
      Default:
      java.util.ArrayList.class

    • mapImplType

      Class<? extends Map> mapImplType
      The map implementation type to apply, defaulting to DEFAULT_MAP_TYPE.
      Returns:
      the map type to apply
      Default:
      java.util.LinkedHashMap.class

    • setImplType

      Class<? extends Set> setImplType
      The set implementation type to apply, defaulting to DEFAULT_SET_TYPE.
      Returns:
      the set type to apply
      Default:
      java.util.LinkedHashSet.class