Interface RetryPolicy

  • All Superinterfaces:
    Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

    public interface RetryPolicy
    extends Supplier<RetryPolicy>
    Mechanism for controlling retry of attempts to load data by an AbstractSource.

    When an AbstractSource attempts to load the underlying data it uses a RetryPolicy to govern if and how it retries the load operation in case of errors.

    The execute(java.util.function.Supplier) method of each policy implementation must perform at least one attempt to load the data, even if it chooses not to retry in case of errors.

    • Method Detail

      • create

        static RetryPolicy create​(Config metaConfig)
                           throws ConfigMappingException,
        Constructs a RetryPolicy from meta-configuration.

        As described with ConfigSource.create(Config), the config system can load ConfigSources using meta-configuration, which supports specifying retry policies. The built-in retry policies 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 retry-policy using the following nested properties:

        • type - name of the retry policy implementation.
          Built-in Retry Policies
          Name Policy Properties
          repeat Tries to load at regular intervals until the retry count reaches retries. See RetryPolicies.repeat(int), and RetryPolicies.Builder for details on the properties.
          • retries (required) in int format
          • delay in Duration format
          • delay-factor - in double format
          • call-timeout - in Duration format
          • overall-timeout - in Duration format
        • class - fully qualified class name of custom retry policy implementation or a builder class that implements a build() method that returns a RetryPolicy.
        For a given config source use either type or class to indicate a retry policy but not both. If both appear the config system ignores the class setting.

        See ConfigSource.create(Config) for example of using built-in retry policies.

        Meta-configuration Support for Custom Retry Policies

        To support settings in meta-configuration, a custom retry policy must follow this pattern.

        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 policy instance. See the built-in mappers defined in ConfigMappers to see what Java types are automatically supported.

        metaConfig - meta-configuration used to initialize returned retry policy instance from.
        new instance of retry policy described by metaConfig
        MissingValueException - in case the configuration tree does not contain all expected sub-nodes required by the mapper implementation to provide instance of Java type.
        ConfigMappingException - in case the mapper fails to map the (existing) configuration tree represented by the supplied configuration node to an instance of a given Java type.
        See Also:
        ConfigSources.load(Supplier[]), ConfigSources.load(Config)
      • execute

        <T> T execute​(Supplier<T> call)
        Invokes the provided Supplier to read the source data and returns that data.

        The implementation of this method incorporates the retry logic.

        Type Parameters:
        T - result type
        call - supplier of T
        loaded data returned by the provided Supplier
      • cancel

        default boolean cancel​(boolean mayInterruptIfRunning)
        Cancels the current use of the retry policy.

        Implementations should correctly handle three cases:

        1. cancel invoked when no invocation of execute is in progress,
        2. cancel invoked when an invocation of execute is active but no attempted load is actually in progress (e.g., a prior attempt failed and the retry policy is waiting for some time to pass before trying again), and
        3. cancel invoked while a load attempt is in progress.
        mayInterruptIfRunning - whether an in-progress load attempt should be interrupted
        false if the task could not be canceled, typically because it has already completed; true otherwise