Retry Mechanism#

The Resilience4j retry module provides fault-tolerance through configurable retry logic with pluggable backoff strategies. The core entry point is RetryImpl, which implements Retry and manages two execution contexts: ContextImpl (synchronous) and AsyncContextImpl (async/CompletableFuture). Configuration is declared via RetryConfig and passed at construction time.

Execution Flow#

Both ContextImpl and AsyncContextImpl follow the same decision tree on each call:

1. onError / onRuntimeError — check whether the exception matches exceptionPredicate 1. Non-matching exceptions are immediately re-thrown and counted as failedWithoutRetry; matching exceptions proceed to sleep-or-throw.
2. throwOrSleepAfterException — increments numOfAttempts. If numOfAttempts >= maxAttempts, publishes a RetryOnErrorEvent and re-throws the original exception 2. Otherwise, calls waitIntervalAfterException.
3. waitIntervalAfterException — calls intervalBiFunction.apply(attempt, Either.left(throwable)) to compute the sleep interval, then calls sleepFunction.accept(interval) 3.
4. onResult — if a resultPredicate is configured and matches the result, the call is treated as a retry trigger 4.
5. onComplete — updates success/failure counters and, when failAfterMaxAttempts is true, throws MaxRetriesExceededException 5.

For async contexts, AsyncContextImpl.onError additionally unwraps CompletionException / ExecutionException before matching 6. Instead of sleeping directly, it returns the computed interval as a long for the caller to schedule 7.

Backoff Interval: IntervalFunction vs. IntervalBiFunction#

Two functional interfaces compute wait intervals:

IntervalBiFunction is the internal contract RetryImpl always uses 8. When only an IntervalFunction is configured, RetryConfig.Builder.build() wraps it automatically via IntervalBiFunction.ofIntervalFunction() 9, discarding the Either parameter at call time. This lets interval functions optionally react differently when a retry was triggered by a result predicate (right side) versus an exception (left side).

Built-in strategies available on IntervalFunction 10:

Default constants: DEFAULT_INITIAL_INTERVAL = 500 ms, DEFAULT_MULTIPLIER = 1.5, DEFAULT_RANDOMIZATION_FACTOR = 0.5 11.

Validation Strategy: Eager (Build-Time) vs. Deferred (Runtime)#

Eager (build-time): IntervalFunction factory methods validate parameters immediately at construction — before any retry runs. checkInterval rejects values < 1 ms, checkRandomizationFactor rejects values outside [0.0, 1.0] 12. Additionally, RetryConfig.Builder.build() enforces that intervalFunction and intervalBiFunction are not set simultaneously, throwing IllegalStateException if both are configured 13. After build(), intervalBiFunction is always non-null 14.

Deferred (runtime): The computed interval value is implicitly validated at runtime. A negative interval returned by intervalBiFunction is treated as a signal to publish a terminal RetryOnErrorEvent and skip the sleep entirely, without throwing an additional exception . The actual constraint on the computed value is only exercised by sleepFunction.accept(interval).

Note: The retry-module-specific IntervalFunction applies a stricter minimum of 10 ms (vs. the core library's 1 ms), so module-level policies may differ.

Exception Propagation#

MaxRetriesExceededException is a RuntimeException created via a static factory createMaxRetriesExceededException(Retry) that includes the retry name and max attempts in the message 23.

Key Source Files#