Annotation Interface ConfiguredOption

@Target(METHOD) @Inherited @Retention(SOURCE) @Repeatable(ConfiguredOptions.class) public @interface ConfiguredOption
A single configuration option. Must be used together with Configured. Usually this should target a builder method that configures appropriate option. If defined on a static method, it must be a {code static T create(X)} method, where X is either io.helidon.config.Config or a single option.

There may be multiple create(X) methods defined on a single interface/class, each of them annotated with a different list of options. In such a case the grouping should be used as defined on these methods. If a method create(Config) exists, it should use the same groups (e.g. if one method defines URI and Proxy, and another method defines a Path, the create(Config) method can accept either (URI, proxy host, proxy port) or (path)).

By default, the name of the method is considered to be the configuration option used. If method contains camel case, it will be changed to lower case hyphenated (this describes the implementation of Helidon specific annotation processor and expectations).

Example - method public Builder listenAddress(String) would be configured by key listen-address.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    ConfiguredOption.Kind
    Option kind.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final boolean
    DEFAULT_REQUIRED
    The default value for required() is false.
    static final String
    UNCONFIGURED
    A string meaning that a value is not specified (to allow empty String as a meaningful value).

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    ConfiguredValue[]
    allowedValues
    For options that have a predefined set of allowed values.
    boolean
    deprecated
    Configure to true if this option is deprecated.
    String
    description
    Description of the configuration option.
    boolean
    experimental
    Set to true for experimental configuration.
    String
    key
    The key of the configuration option as used in config.
    ConfiguredOption.Kind
    kind
    Kind of this option.
    boolean
    mergeWithParent
    When set to true, this property will be part of the parent structure (e.g.
    boolean
    provider
    Set to true if the configuration may be provided by another module not know to us.
    boolean
    required
    Whether this option is truly required (e.g.
    Class<?>
    type
    The type of the configuration option.
    String
    value
    Default value of this option if not configured explicitly.

  • Field Details

    • UNCONFIGURED

      static final String UNCONFIGURED
      A string meaning that a value is not specified (to allow empty String as a meaningful value).
      See Also:

    • DEFAULT_REQUIRED

      static final boolean DEFAULT_REQUIRED
      The default value for required() is false.
      See Also:

  • Element Details

    • key

      String key
      The key of the configuration option as used in config.
      Returns:
      config key
      Default:
      ""

    • type

      Class<?> type
      The type of the configuration option.

      If the type is not explicitly configured, it is derived from the annotated method. If the method has parameters, the type of the first parameter is used. Otherwise, the method must return a type is used.

      Returns:
      type of the configuration option
      Default:
      io.helidon.config.metadata.ConfiguredOption.class

    • description

      String description
      Description of the configuration option. Defaults to the Javadoc first sentence of the annotated element.
      Returns:
      description of the configuration option
      Default:
      ""

    • required

      boolean required
      Whether this option is truly required (e.g. the option must be present in configuration, otherwise the component would fail). This MUST NOT be configured together with default value, as that would make this option optional (as a default value exists).
      Returns:
      true for required option, false for options that are optional.
      See Also:
      Default:
      false

    • value

      String value
      Default value of this option if not configured explicitly.
      Returns:
      default value
      Default:
      "io.helidon.config.metadata.ConfiguredOption.UNCONFIGURED"

    • experimental

      boolean experimental
      Set to true for experimental configuration.
      Returns:
      whether this option is experimental
      Default:
      false

    • kind

      ConfiguredOption.Kind kind
      Kind of this option. Defaults to ConfiguredOption.Kind.VALUE, autodetects ConfiguredOption.Kind.LIST if the parameter is an actual List, Set or Iterable. ConfiguredOption.Kind.MAP is detected as well, though the type must be a String to a primitive or string
      Returns:
      kind of configuration option
      Default:
      VALUE

    • provider

      boolean provider
      Set to true if the configuration may be provided by another module not know to us. The provider must then be configured to Configured.provides() this type so code can be correctly generated.

      If the method returns a list, the provider configuration must be under config key providers under the configured option. On the same level as providers, there can be discover-services boolean defining whether to look for services from service loader even if not configured in the configuration.

      Option called myProvider that returns a single provider, or an Optional provider example in configuration: 

      my-type:
  my-provider:
    provider-id:
      provider-key1: "providerValue"
      provider-key2: "providerValue"

      Option called myProviders that returns a list of providers in configuration: 

      my-type:
  my-providers:
    discover-services: true
    providers:
      provider-id:
        provider-key1: "providerValue"
        provider-key2: "providerValue"
      provider2-id:
        provider2-key1: "provider2Value"
      Returns:
      whether this requires a provider with configuration, defaults to false
      Default:
      false

    • allowedValues

      ConfiguredValue[] allowedValues
      For options that have a predefined set of allowed values.
      Returns:
      allowed values
      Default:
      {}

    • deprecated

      boolean deprecated
      Configure to true if this option is deprecated.
      Returns:
      whether this configured option is deprecated
      Default:
      false

    • mergeWithParent

      boolean mergeWithParent
      When set to true, this property will be part of the parent structure (e.g. the key() must be empty, and this must be a complex node).
      Returns:
      whether to merge the child nodes directly with parent node without a key
      Default:
      false