Package ai.extend.wrapper.utilities.polling

Class Polling

  • public final class Polling
extends java.lang.Object
    Utility class for polling operations with hybrid polling strategy.

    This class provides methods to poll an API endpoint until a terminal condition is met. The default strategy uses fast polling at fixed intervals for an initial period, then switches to exponential backoff with jitter.

    Default behavior:

    • Fast phase: Poll every 1 second for the first 30 seconds
    • Backoff phase: Exponential backoff with 1.15x multiplier, max 30 second delay

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static int calculateBackoffDelay​(int attempt, int initialDelayMs, int maxDelayMs, double jitterFraction)
      Calculates the next delay using exponential backoff with default 2x multiplier.
      static int calculateBackoffDelay​(int attempt, int initialDelayMs, int maxDelayMs, double jitterFraction, double backoffMultiplier)
      Calculates the next delay using exponential backoff with proportional jitter.
      static int calculateHybridDelay​(long elapsedMs, int fastPollDurationMs, int fastPollIntervalMs, int initialDelayMs, int maxDelayMs, double backoffMultiplier, double jitterFraction)
      Calculates the delay for a hybrid polling strategy based on elapsed time.
      static <T> T pollUntilDone​(java.util.function.Supplier<T> retrieve, java.util.function.Predicate<T> isTerminal)
      Polls a retrieve function until a terminal condition is met, using default options.
      static <T> T pollUntilDone​(java.util.function.Supplier<T> retrieve, java.util.function.Predicate<T> isTerminal, PollingOptions options)
      Polls a retrieve function until a terminal condition is met.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • calculateBackoffDelay

        public static int calculateBackoffDelay​(int attempt,
                                        int initialDelayMs,
                                        int maxDelayMs,
                                        double jitterFraction,
                                        double backoffMultiplier)
        Calculates the next delay using exponential backoff with proportional jitter.

        Formula: min(initialDelay * multiplier^attempt, maxDelay) * (1 + random(-jitter, +jitter))

        Parameters:
        attempt - The current attempt number (0-based)
        initialDelayMs - The initial delay in milliseconds
        maxDelayMs - The maximum delay in milliseconds
        jitterFraction - The jitter fraction (e.g., 0.25 for ±25%)
        backoffMultiplier - The multiplier for exponential backoff (default: 2.0)
        Returns:
        The calculated delay in milliseconds

      • calculateBackoffDelay

        public static int calculateBackoffDelay​(int attempt,
                                        int initialDelayMs,
                                        int maxDelayMs,
                                        double jitterFraction)
        Calculates the next delay using exponential backoff with default 2x multiplier.
        Parameters:
        attempt - The current attempt number (0-based)
        initialDelayMs - The initial delay in milliseconds
        maxDelayMs - The maximum delay in milliseconds
        jitterFraction - The jitter fraction (e.g., 0.25 for ±25%)
        Returns:
        The calculated delay in milliseconds

      • calculateHybridDelay

        public static int calculateHybridDelay​(long elapsedMs,
                                       int fastPollDurationMs,
                                       int fastPollIntervalMs,
                                       int initialDelayMs,
                                       int maxDelayMs,
                                       double backoffMultiplier,
                                       double jitterFraction)
        Calculates the delay for a hybrid polling strategy based on elapsed time.

        During the fast polling phase (elapsed < fastPollDurationMs), returns a fixed interval with jitter. After the fast phase ends, switches to exponential backoff.

        Parameters:
        elapsedMs - Total elapsed time since polling started
        fastPollDurationMs - Duration of fast polling phase in milliseconds
        fastPollIntervalMs - Interval between polls during fast phase in milliseconds
        initialDelayMs - Initial delay for backoff phase in milliseconds
        maxDelayMs - Maximum delay cap in milliseconds
        backoffMultiplier - Multiplier for exponential backoff
        jitterFraction - Jitter fraction for randomization
        Returns:
        The delay in milliseconds until the next poll

      • pollUntilDone

        public static <T> T pollUntilDone​(java.util.function.Supplier<T> retrieve,
                                  java.util.function.Predicate<T> isTerminal,
                                  PollingOptions options)
                           throws PollingTimeoutError
        Polls a retrieve function until a terminal condition is met.

        This method uses a hybrid polling strategy: fast polling at fixed intervals for an initial period, then exponential backoff with jitter. This provides low latency for quick operations while still reducing server load for longer ones.

        Default behavior:

        • Fast phase: Poll every 1 second for the first 30 seconds
        • Backoff phase: Exponential backoff with 1.15x multiplier, max 30 second delay
        Type Parameters:
        T - The type of result returned by the retrieve function
        Parameters:
        retrieve - A supplier that retrieves the current state
        isTerminal - A predicate that returns true when polling should stop
        options - Polling configuration options
        Returns:
        The final result when a terminal state is reached
        Throws:
        PollingTimeoutError - if maxWaitMs is set and exceeded

      • pollUntilDone

        public static <T> T pollUntilDone​(java.util.function.Supplier<T> retrieve,
                                  java.util.function.Predicate<T> isTerminal)
        Polls a retrieve function until a terminal condition is met, using default options.

        Polls indefinitely until a terminal state is reached using hybrid polling strategy.

        Type Parameters:
        T - The type of result returned by the retrieve function
        Parameters:
        retrieve - A supplier that retrieves the current state
        isTerminal - A predicate that returns true when polling should stop
        Returns:
        The final result when a terminal state is reached