Annotation Interface Option.Provider

Enclosing class:
Option
@Target(METHOD) @Inherited @Retention(CLASS) public static @interface Option.Provider
Mark option as sourced from services discovered by a ServiceLoader, or by Helidon Service Registry when Prototype.RegistrySupport is enabled. Use if the configuration may be provided by another module not known to us.

When the option is also Option.Configured, discovered configured providers are used to create services from configuration.

A configured provider option uses the option's configured key as the provider configuration node. For example, if the provider option key is my-providers, provider entries are read from my-providers. There is no extra nested providers key unless the option itself is configured with that key.

To control whether to discover services or not for a configured provider option, you can specify a sibling boolean key named <option-config-key>-discover-services, such as my-providers-discover-services. This is aligned with the generated methods on the builder and overrides discoverServices() defined on this annotation.

The configuration key rules are the same regardless whether the method returns a single value, a single Optional value, a list of values, or an optional list of values. A single value or optional value must have at most one configured provider entry.

When using an optional list, an absent configuration node does not by itself set the optional value; the value stays empty unless builder values or service discovery provide entries. An explicitly empty list or object configuration node produces Optional.of(List.of()).

The following examples first use the compatibility defaults, TYPE_AND_NAME with AUTO. With those defaults, either object or list form is accepted. Option myProvider returning one value, or an Optional value, can use object form: 

my-type:
  my-provider:
    provider-id: # object key supplies the instance name
      type: provider-type
      provider-key1: "providerValue"
      provider-key2: "providerValue"

Option myProviders returning a Java List can use the same object form; the Java return type does not require list-form configuration. This example configures two instances of the same provider type: 

my-type:
  my-providers-discover-services: true # default of this value is controlled by annotation
  my-providers:
    first-provider:
      type: provider-type
      provider-key1: "providerValue"
      provider-key2: "providerValue"
    second-provider:
      type: provider-type
      provider-key1: "anotherValue"
The same option can instead use list form with the compatibility defaults: 
my-type:
  my-providers:
    - type: provider-type
      name: first-provider
      provider-key1: "providerValue"
      provider-key2: "providerValue"
    - type: provider-type
      name: second-provider
      provider-key1: "anotherValue"
In object form, each object key supplies an instance name and those names are therefore globally unique within the object. Object form does not define the order in which values are materialized. List form preserves the configured order, may reuse a name for a different provider type, and rejects an exact duplicate (type, name) pair. Object form is therefore intentionally less expressive than list form for TYPE_AND_NAME.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Option.Provider.ConfigForm
    Accepted outer container for configured provider entries.
    static enum 
    Option.Provider.Identity
    Identity model for configured provider instances.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    Class<?>
    value
    Provider contract used to discover implementations for this option.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Option.Provider.ConfigForm
    configForm
    Outer configuration container accepted for configured provider entries.
    boolean
    discoverServices
    Whether service discovery may add option values that do not have corresponding configuration.
    Option.Provider.Identity
    identity
    Values that constitute the identity of each configured provider instance.

  • Element Details

    • value

      Class<?> value
      Provider contract used to discover implementations for this option.

      For a configured option, implementations of this contract are configured providers that create the option's values from configuration. For a non-configured option, implementations of this contract are themselves the option values. The configured-provider identity and configuration-form properties do not apply to a non-configured option.

      Returns:
      provider contract used for discovery

    • discoverServices

      boolean discoverServices
      Whether service discovery may add option values that do not have corresponding configuration.

      For a configured provider option, provider implementations are always discovered so they can create entries that are present in configuration. A value of false only prevents those providers from adding unconfigured default values; it does not disable the discovery needed to create configured entries. For a non-configured provider option, false prevents discovered implementations from being added as option values.

      Discovery uses the service loader, or Helidon Service Registry when Prototype.RegistrySupport is enabled. For configured provider options, this can be overridden by a sibling configuration option named <option-config-key>-discover-services. For a non-configured provider option, this value initializes the generated discovery flag, which can still be changed using the generated builder method. The default is true.

      Returns:
      whether service discovery may add values without matching configuration by default
      Default:
      true

    • identity

      Option.Provider.Identity identity
      Values that constitute the identity of each configured provider instance.

      Identity is independent of configuration syntax. It defines which values distinguish configured instances, not whether the outer configuration is written as an object or a list. For example, TYPE_ONLY can be combined with LIST, and TYPE_AND_NAME can be combined with OBJECT.

      With TYPE_AND_NAME, an object key supplies the instance name, so object-form names are globally unique. List form may reuse a name for a different provider type, but an exact duplicate (type, name) pair is invalid. The default is TYPE_AND_NAME. This property is ignored when the provider option is not also configured.

      Returns:
      configured provider identity model
      Default:
      TYPE_AND_NAME

    • configForm

      Option.Provider.ConfigForm configForm
      Outer configuration container accepted for configured provider entries.

      The form is independent of provider identity. It controls only whether the configured provider collection is an object, a list, or either. It is also independent of the option's Java type: a Java List option may use object-form configuration. The selected form does not constrain the provider-specific value within each entry beyond the metadata required by the selected identity model.

      AUTO preserves compatibility by resolving to OBJECT for TYPE_ONLY, and to OBJECT_OR_LIST for TYPE_AND_NAME. Object form has unspecified materialization order; list form preserves configured order. An explicit form overrides the automatic choice. The default is AUTO. This property is ignored when the provider option is not also configured.

      Returns:
      accepted outer configuration form
      Default:
      AUTO