Module io.helidon.config.metadata
Package io.helidon.config.metadata

Annotation Interface ConfiguredOption

@Target(METHOD) @Inherited @Retention(CLASS) @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.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    ConfiguredValue[]
    allowedValues
    For options that have a predefined set of allowed values.
    boolean
    builderMethod
    Is this method also available as a public builder method, or is it only used for configuration.
    boolean
    configured
    This can be set to false for options, where this annotation is used for other purposes, and in fact does not indicate something to be loaded from configuration.
    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
    providerDiscoverServices
    Whether to discover all services using a service loader by default.
    Class<?>
    providerType
    If provider(), this points to the provider interface that is used to discover implementations.
    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 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).

  • 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. By default it is the type of the first parameter. If this annotation exists on a class, type defaults to String.
      Returns:
      type of the configuration option
      Default:
      io.helidon.config.metadata.ConfiguredOption.class

    • description

      String description
      Description of the configuration option. By default javadoc of the builder method is used. If this annotation exists on a class, description is mandatory.
      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. In addition, the providerType() must be set to the correct service provider interface, 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 (this would override providerDiscoverServices() defined on this annotation.

      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 # default of this value is controlled by annotation
     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
      See Also:
      Default:
      false

    • providerType

      Class<?> providerType
      If provider(), this points to the provider interface that is used to discover implementations.
      Returns:
      type of the provider.
      Default:
      io.helidon.config.metadata.ConfiguredOption.class

    • providerDiscoverServices

      boolean providerDiscoverServices
      Whether to discover all services using a service loader by default. When set to true, all services discovered by the service loader will be added (even if no configuration node exists for them). When se to false, only services that have a configuration node will be added. This can be overridden by discover-services configuration option under this option's key.
      Returns:
      whether to discover services by default for a provider
      Default:
      true

    • 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

    • builderMethod

      boolean builderMethod
      Is this method also available as a public builder method, or is it only used for configuration.
      Returns:
      whether the method is also a builder method (true), or only config method (false)
      Default:
      true

    • configured

      boolean configured
      This can be set to false for options, where this annotation is used for other purposes, and in fact does not indicate something to be loaded from configuration.
      Returns:
      whether this option should be configured from configuration
      Default:
      true