Package io.helidon.config.spi

Interface PollingStrategy

  • All Superinterfaces:
    Supplier<PollingStrategy>
    All Known Implementing Classes:
    EtcdWatchPollingStrategy
    public interface PollingStrategy
extends Supplier<PollingStrategy>
    Mechanism for notifying interested subscribers when they should check for changes that might have been made to the data used to create a Config tree, as accessed through ConfigSources.

    Once it loads a Config tree from ConfigSources the config system does not itself change the in-memory Config tree. Even so, the underlying data available via the tree's ConfigSources can change. Implementations of PollingStrategy other interested code to learn when changes to that underlying data might have occurred.

    In implementations of PollingStrategy the ticks() method returns a Flow.Publisher of PollingStrategy.PollingEvents to which the application or the ConfigSources themselves can subscribe. Generally, each event is a hint to the application or a ConfigSource itself that it should check to see if any of the underlying config data it relies on might have changed. Note that a PollingStrategy's publication of an event does not necessarily guarantee that the underlying data has in fact changed, although this might be true for some PollingStrategy implementations.

    Typically a custom ConfigSource implementation creates a Flow.Subscriber which it uses to subscribe to the Flow.Publisher that is returned from the PollingStrategy.ticks() method. When that subscriber receives a PollingEvent it triggers the ConfigSource to reload the configuration from the possibly changed underlying data. For example, each AbstractParsableConfigSource can use a different PollingStrategy.

    As described with ConfigSource.create(Config), the config system can load ConfigSources using meta-configuration, which supports specifying polling strategies. All built-in polling strategies and custom ones are supported. (The support is tightly connected with AbstractSource extensions and will not be automatically provided by any another config source implementations.)

    The meta-configuration for a config source can set the property polling-strategy using the following nested properties:

    • type - name of the polling strategy implementation.
      Built-in Polling Strategies
      Name Strategy Required Properties
      regular Scheduled polling at regular intervals. See PollingStrategies.regular(Duration). interval in Duration format, e.g. PT15S means 15 seconds
      watch Filesystem monitoring of the Path specified in the config source definition. See PollingStrategies.watch(Path).

      Use this strategy only with config sources based on AbstractSource.Builder that are paramaterized with Path. This includes null classpath, file and directory config sources.

      		n/a

    • class - fully-qualified class name of a custom polling strategy implementation or a builder class that implements a build() method that returns a PollingStrategy.
    For a given config source use either type or class to indicate a polling strategy but not both. If both appear the config system ignores the class setting.

    Meta-configuration Support for Custom Polling Strategies

    To support settings in meta-configuration, a custom polling strategy must follow these patterns.
    1. Auto-configuration from meta-configuration properties

      The implementation class should define a Java bean property for each meta-configuration property it needs to support. The config system uses mapping functions to convert the text in the meta-configuration into the correct Java type and then assigns the value to the correspondingly-named Java bean property defined on the custom strategy instance. See the built-in mappers defined in ConfigMappers to see what Java types are automatically supported.

    2. Accessing the ConfigSource meta-config attributes

      The custom polling strategy can get access to the same meta-configuration attributes that are used to construct the associated ConfigSource. To do so the custom implementation class should implement a constructor that accepts the same Java type as that returned by the AbstractSource.Builder.target() method on the builder that is used to construct the ConfigSource.

      For example, a custom polling strategy useful with ConfigSources based on a Path would implement a constructor that accepts a Path argument.

    See Also:
    AbstractSource.Builder.pollingStrategy(Supplier), Flow.Publisher, PollingStrategies - access built-in implementations.

    • Method Detail

      • ticks

        Flow.Publisher<PollingStrategy.PollingEvent> ticks()
        Returns a Flow.Publisher which fires PollingStrategy.PollingEvents.

        Note that PollingStrategy implementations can generate PollingEvents whether or not any subscribers have subscribed to the publisher of the events.

        Subscribers typically invoke Flow.Subscription.request(long) asking for one event initially, and then after it has processed each event the subscriber requests one more event.

        The subscriber might not receive every event broadcast, for example if it subscribes to the publisher after an event has been delivered to the publisher.

        Each PollingStrategy implementation chooses which executor to use for notifying subscribers. The recommended practice is to use the same thread as the polling strategy implementation runs on.

        Returns:
        a publisher of events