Migrate from Resilience4j

How Resilience4j's registries, configs, decorators and Spring annotations map to resilience4cata, what has no equivalent, and what behaves differently.

Should you migrate?

resilience4cata covers eight policies (retry, hedge, circuit breaker, rate limiter, adaptive limit, timeout, bulkhead, fallback) for plain Java 21+, with code generated at compile time. Stay on Resilience4j if you need any of these, which resilience4cata does not have yet:

• Spring Boot 3, CDI or AspectJ integration (resilience4cata integrates with Spring Boot 4.1+ only, below);
• Reactor, RxJava or Kotlin coroutine operators (resilience4cata supports CompletionStage / CompletableFuture only);
• a thread-pool bulkhead, a cache, or a time limiter for arbitrary futures;
• changing a policy's configuration at runtime (resilience4cata resolves configuration once, by design);
• a Java version before 21.

Consider migrating if per-call overhead and allocation matter to you (see Performance), if you want misconfiguration caught at compile time, or if you prefer plain annotations and generated code you can read over AOP proxies.

The mental model

Concept mapping

Configuration mapping

Resilience4j builder methods (Spring Boot properties use the same names in kebab-case) and the resilience4cata attribute with the same role. Defaults differ in places; the Default columns are each library's own.

Circuit breaker

Retry

Rate limiter, timeout, bulkhead

Warning Three defaults catch people out: resilience4cata's retry uses exponential backoff with full jitter from 200 ms, not a fixed 500 ms; its rate limiter rejects at once instead of waiting up to 5 s; and its breaker does not time calls unless you set slowCallDuration. Set them explicitly when you migrate.

Hedge

Resilience4j's resilience4j-hedge module (2.x) is programmatic and async only, like ours (no Spring annotation), and starts at most one hedge.

The semantics differ: in Resilience4j the first attempt to complete wins, so a fast failure of either attempt fails the call; in resilience4cata the first success wins, a failure in hedgeOn starts the next attempt at once, and the call fails only when every attempt has failed (or one fails with an abortOn failure). The loser is cancelled, and the circuit breaker, bulkhead and timeout inside the hedge release what it held.

Behavioural differences

The order

Fallback → Retry (or Hedge) → CircuitBreaker → RateLimiter → AdaptiveLimit → Timeout → Bulkhead → method by default, whatever the order of the annotations. It matches Resilience4j's default Spring aspect order for the policies both have. Where Resilience4j changes the order globally with <module>AspectOrder properties, resilience4cata changes it per method, type or bundle with @PolicyOrder, at compile time; the fallback stays outermost.

An open breaker stops retries

A retry never retries CallNotPermittedException, whatever its abortOn says, so once the breaker opens, the retry gives up at once instead of retrying into it. In Resilience4j you add that exception to ignoreExceptions yourself.

Errors are not recorded or retried by default

recordOn and retryOn default to Exception: an Error (for example OutOfMemoryError, AssertionError) is not retried and counts as a success for the breaker. @Fallback(applyOn) defaults to Throwable, so a fallback does catch Errors unless you add them to skipOn.

Timeouts interrupt the caller's thread

A sync @Timeout does not move the call to another thread: it runs where you called it, and a shared watchdog interrupts it when time is up. Code that ignores interrupts runs to completion before the caller gets CallTimeoutException. Timeouts are never early and at most about two watchdog ticks late (1–50 ms ticks). See Timeout.

Breakers move to half-open on the next call

There is no timer that moves an open breaker to half-open: the first call after waitInOpen does. A snapshot taken in between still says OPEN.

Configuration is resolved once

Annotation values, named configs and external configuration are combined when the instance is created and never change afterwards. There is no changeConfig, no refresh event, no hot reload. Listeners too are fixed when the registry is built.

Self-invocation in the interface style

With Resilient.of, a call from your implementation to its own method skips the policies, like a Spring proxy. Annotated classes (the subclass style) do intercept this.method(). See Annotated classes.

Instances are per method unless named

A Resilience4j instance is shared by everything that uses its name. In resilience4cata each annotated method gets its own instances, with an id such as com.acme.StockClient#stock(java.lang.String); give methods the same name to share one (their resolved configurations must then be identical, R4C-REG-008). @Timeout has no name.

The processor is mandatory

Without the annotation processor nothing is generated and Resilient.of fails with R4C-RT-003. There is no reflection or proxy fallback.

The same service, both ways

A stock lookup with a retry (3 attempts, 500 ms apart, only on IOException), a breaker shared under the name inventory, a 2 s timeout and a fallback.

Resilience4j, with decorators:

CircuitBreaker breaker = CircuitBreaker.of("inventory", CircuitBreakerConfig.custom()
        .failureRateThreshold(50)
        .slidingWindowSize(20)
        .minimumNumberOfCalls(10)
        .waitDurationInOpenState(Duration.ofSeconds(30))
        .permittedNumberOfCallsInHalfOpenState(3)
        .build());
Retry retry = Retry.of("inventory", RetryConfig.custom()
        .maxAttempts(3)
        .waitDuration(Duration.ofMillis(500))
        .retryExceptions(IOException.class)
        .ignoreExceptions(CallNotPermittedException.class)
        .build());
TimeLimiter timeLimiter = TimeLimiter.of(Duration.ofSeconds(2));
ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(4);

Supplier<CompletionStage<Integer>> decorated = Decorators
        .ofCompletionStage(() -> CompletableFuture.supplyAsync(() -> client.stock(sku), scheduler)) // a blocking call moved to a thread
        .withTimeLimiter(timeLimiter, scheduler)
        .withCircuitBreaker(breaker)
        .withRetry(retry, scheduler)
        .withFallback(List.of(Exception.class), e -> -1)
        .decorate();
int units = decorated.get().toCompletableFuture().join();

resilience4cata: the annotations on the interface,

public interface StockClient {

    @Fallback(method = "unknownStock")
    @Retry(name = "inventory", maxAttempts = 3, delay = "500ms", backoff = Backoff.FIXED, jitter = Jitter.NONE,
            retryOn = IOException.class)
    @CircuitBreaker(name = "inventory", failureRateThreshold = 50, windowSize = 20, minimumCalls = 10,
            waitInOpen = "30s", halfOpenCalls = 3)
    @Timeout("2s")
    int stock(String sku) throws IOException;

    default int unknownStock(String sku, Exception failure) {
        return -1;
    }
}

and the call site:

ResilienceRegistry registry = ResilienceTesting.registry(clock).build(); // ResilienceRegistry.builder() in production
StockClient stock = Resilient.of(StockClient.class, sku -> {
    calls.incrementAndGet();
    throw new IOException("inventory unreachable");
}, registry);

int units = stock.stock("SKU-1"); // three attempts 500 ms apart, then the fallback

The synchronous call stays synchronous: there is no executor, because the timeout interrupts the caller's thread instead of moving the call to another one.

External configuration. Spring Boot's application.yml keys and their resilience4cata equivalents in a .properties file (instances.inventory.* overrides the annotation for that instance; defaults.* only fills in attributes that the annotation does not set):

# resilience4j.circuitbreaker.instances.inventory.sliding-window-size=50
instances.inventory.circuitBreaker.windowSize=50
# resilience4j.circuitbreaker.instances.inventory.wait-duration-in-open-state=10s
instances.inventory.circuitBreaker.waitInOpen=10s
# resilience4j.retry.instances.inventory.max-attempts=5
instances.inventory.retry.maxAttempts=5
# resilience4j.circuitbreaker.configs.default.failure-rate-threshold=40
defaults.circuitBreaker.failureRateThreshold=40

Load it with ResilienceConfig.load() (as resilience4cata.properties on the classpath) or ResilienceConfig.builder().classpath(…), then config.applyTo(ResilienceRegistry.builder()). See Configuration.

From resilience4j-spring-boot3

resilience4cata-spring replaces resilience4j-spring-boot3 on Spring Boot 4.1 or newer (Spring Boot guide). Drop spring-boot-starter-aop: nothing is woven or proxied; the annotation processor generates the protected classes, and the integration makes Spring instantiate them.

The same keys in application.yml:

# resilience4j.circuitbreaker.instances.inventory.sliding-window-size: 50
# resilience4j.circuitbreaker.configs.default.failure-rate-threshold: 40
# resilience4j.retry.instances.inventory.max-attempts: 5
resilience4cata:
  defaults:
    circuit-breaker:
      failure-rate-threshold: 40
  instances:
    inventory:
      circuit-breaker:
        window-size: 50
      retry:
        max-attempts: 5

Typos fail the startup with the file and line of the key, instead of being ignored.

Step by step

1. Add the dependencies, including the processor on the processor path (Installation); with Spring Boot, resilience4cata-spring (above).
2. For each decorated call, put the call behind an interface (or annotate the class), and translate the configuration with the tables above. Set backoff, jitter and maxWait explicitly where the defaults differ.
3. Replace Decorators/Spring annotations with resilience4cata annotations and Resilient.of (or Resilient.create for annotated classes). Calls you cannot put behind an interface go through a Pipeline.
4. Move event consumers to ResilienceRegistry.Builder.listen(…), and metrics to the Micrometer module.
5. Replace time-based tests with ManualClock.
6. Build with -Xlint:all -Werror if you like: generated code compiles without warnings.