io.github.resilience4j:resilience4j-cache

= Fault tolerance library designed for functional programming :author: Robert Winkler and Bohdan Storozhuk :icons: :toc: macro :numbered: 1 ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]

image:https://github.com/resilience4j/resilience4j/actions/workflows/gradle-build.yml/badge.svg["Build Status"] image:https://img.shields.io/nexus/r/io.github.resilience4j/resilience4j-circuitbreaker?server=https%3A%2F%2Foss.sonatype.org["Release"] image:https://img.shields.io/nexus/s/io.github.resilience4j/resilience4j-circuitbreaker?server=https%3A%2F%2Foss.sonatype.org["Snapshot"] image:http://img.shields.io/badge/license-ASF2-blue.svg["Apache License 2", link="http://www.apache.org/licenses/LICENSE-2.0.txt"]

image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=coverage["Coverage", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"] image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=sqale_rating["Maintainability", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"] image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=reliability_rating["Reliability", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"] image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=security_rating["Security", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"] image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=vulnerabilities["Vulnerabilities", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"] image:https://sonarcloud.io/api/project_badges/measure?project=resilience4j_resilience4j&metric=bugs["Bugs", link="https://sonarcloud.io/dashboard?id=resilience4j_resilience4j"]

image:https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg["SWUbanner",link="https://vshymanskyy.github.io/StandWithUkraine"]

toc::[]

== Introduction

Resilience4j is a lightweight fault tolerance library designed for functional programming. Resilience4j provides higher-order functions (decorators) to enhance any functional interface, lambda expression or method reference with a Circuit Breaker, Rate Limiter, Retry or Bulkhead. You can stack more than one decorator on any functional interface, lambda expression or method reference. The advantage is that you have the choice to select the decorators you need and nothing else.

Resilience4j 2 requires Java 17.

[source,java]

// Create a CircuitBreaker with default configuration CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("backendService");

// Create a Retry with default configuration // 3 retry attempts and a fixed time interval between retries of 500ms Retry retry = Retry.ofDefaults("backendService");

// Create a Bulkhead with default configuration Bulkhead bulkhead = Bulkhead.ofDefaults("backendService");

Supplier supplier = () -> backendService .doSomething(param1, param2);

// Decorate your call to backendService.doSomething() // with a Bulkhead, CircuitBreaker and Retry // **note: you will need the resilience4j-all dependency for this Supplier decoratedSupplier = Decorators.ofSupplier(supplier) .withCircuitBreaker(circuitBreaker) .withBulkhead(bulkhead) .withRetry(retry) .decorate();

// Execute the decorated supplier and recover from any exception String result = Try.ofSupplier(decoratedSupplier) .recover(throwable -> "Hello from Recovery").get();

// When you don't want to decorate your lambda expression, // but just execute it and protect the call by a CircuitBreaker. String result = circuitBreaker .executeSupplier(backendService::doSomething);

// You can also run the supplier asynchronously in a ThreadPoolBulkhead ThreadPoolBulkhead threadPoolBulkhead = ThreadPoolBulkhead .ofDefaults("backendService");

// The Scheduler is needed to schedule a timeout on a non-blocking CompletableFuture ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(3); TimeLimiter timeLimiter = TimeLimiter.of(Duration.ofSeconds(1));

CompletableFuture future = Decorators.ofSupplier(supplier) .withThreadPoolBulkhead(threadPoolBulkhead) .withTimeLimiter(timeLimiter, scheduler) .withCircuitBreaker(circuitBreaker) .withFallback(asList(TimeoutException.class, CallNotPermittedException.class, BulkheadFullException.class), throwable -> "Hello from Recovery") .get().toCompletableFuture();

NOTE: With Resilience4j you don’t have to go all-in, you can https://mvnrepository.com/artifact/io.github.resilience4j[*pick what you need*].

== Documentation

Setup and usage is described in our https://resilience4j.readme.io/docs[User Guide].

• https://github.com/resilience4j-docs-ja/resilience4j-docs-ja[有志による日本語訳(非公式) Japanese translation by volunteers(Unofficial)]

• https://github.com/lmhmhl/Resilience4j-Guides-Chinese[这是Resilience4j的非官方中文文档 Chinese translation by volunteers(Unofficial)]

== Overview

Resilience4j provides several core modules:

• resilience4j-circuitbreaker: Circuit breaking
• resilience4j-ratelimiter: Rate limiting
• resilience4j-bulkhead: Bulkheading
• resilience4j-retry: Automatic retrying (sync and async)
• resilience4j-timelimiter: Timeout handling
• resilience4j-cache: Result caching

There are also add-on modules for metrics, Feign, Kotlin, Spring, Ratpack, Vertx, RxJava2 and more.

NOTE: Find out full list of modules in our https://resilience4j.readme.io/docs#section-modularization[User Guide].

TIP: For core modules package or Decorators builder see https://mvnrepository.com/artifact/io.github.resilience4j/resilience4j-all[resilience4j-all].

== Resilience patterns

[cols="<.<*", options="header"] |=== |name |how does it work? |description |links

|Retry |repeats failed executions |Many faults are transient and may self-correct after a short delay. |<<circuitbreaker-retry-fallback,overview>>, https://resilience4j.readme.io/docs/retry[documentation], https://resilience4j.readme.io/docs/getting-started-3#annotations[Spring]

|Circuit Breaker |temporary blocks possible failures |When a system is seriously struggling, failing fast is better than making clients wait. |<<circuitbreaker-retry-fallback,overview>>, https://resilience4j.readme.io/docs/circuitbreaker[documentation], https://resilience4j.readme.io/docs/feign[Feign], https://resilience4j.readme.io/docs/getting-started-3#annotations[Spring]

|Rate Limiter |limits executions/period |Limit the rate of incoming requests. |<<ratelimiter,overview>>, https://resilience4j.readme.io/docs/ratelimiter[documentation], https://resilience4j.readme.io/docs/feign[Feign], https://resilience4j.readme.io/docs/getting-started-3#annotations[Spring]

|Time Limiter |limits duration of execution |Beyond a certain wait interval, a successful result is unlikely. |https://resilience4j.readme.io/docs/timeout[documentation], https://resilience4j.readme.io/docs/getting-started-3#annotations[Spring]

|Bulkhead |limits concurrent executions |Resources are isolated into pools so that if one fails, the others will continue working. |<<bulkhead,overview>>, https://resilience4j.readme.io/docs/bulkhead[documentation], https://resilience4j.readme.io/docs/getting-started-3#annotations[Spring]

|Cache |memorizes a successful result |Some proportion of requests may be similar. |https://resilience4j.readme.io/docs/cache[documentation]

|Fallback |provides an alternative result for failures |Things will still fail - plan what you will do when that happens. |<<circuitbreaker-retry-fallback,Try::recover>>, https://resilience4j.readme.io/docs/getting-started-3#section-annotations[Spring], https://resilience4j.readme.io/docs/feign[Feign]

|===

Above table is based on https://github.com/App-vNext/Polly#resilience-policies[Polly: resilience policies].

NOTE: To find more information about resilience patterns check link:#Talks[Talks] section. Find out more about components in our https://resilience4j.readme.io/docs/getting-started-2[User Guide].

== Spring Boot

Setup and usage in Spring Boot 2 is demonstrated https://github.com/resilience4j/resilience4j-spring-boot2-demo[here].

== Usage examples

[[circuitbreaker-retry-fallback]] === CircuitBreaker, Retry and Fallback

The following example shows how to decorate a lambda expression (Supplier) with a CircuitBreaker and how to retry the call at most 3 times when an exception occurs. You can configure the wait interval between retries and also configure a custom backoff algorithm.

The example uses Vavr's Try Monad to recover from an exception and invoke another lambda expression as a fallback, when even all retries have failed.

[source,java]

// Simulates a Backend Service public interface BackendService { String doSomething(); }

// Create a CircuitBreaker (use default configuration) CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("backendName"); // Create a Retry with at most 3 retries and a fixed time interval between retries of 500ms Retry retry = Retry.ofDefaults("backendName");

// Decorate your call to BackendService.doSomething() with a CircuitBreaker Supplier decoratedSupplier = CircuitBreaker .decorateSupplier(circuitBreaker, backendService::doSomething);

// Decorate your call with automatic retry decoratedSupplier = Retry .decorateSupplier(retry, decoratedSupplier);

// Use of Vavr's Try to // execute the decorated supplier and recover from any exception String result = Try.ofSupplier(decoratedSupplier) .recover(throwable -> "Hello from Recovery").get();

// When you don't want to decorate your lambda expression, // but just execute it and protect the call by a CircuitBreaker. String result = circuitBreaker.executeSupplier(backendService::doSomething);

==== CircuitBreaker and RxJava2

The following example shows how to decorate an Observable by using the custom RxJava operator.

[source,java]

CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("testName"); Observable.fromCallable(backendService::doSomething) .compose(CircuitBreakerOperator.of(circuitBreaker))

NOTE: Resilience4j also provides RxJava operators for RateLimiter, Bulkhead, TimeLimiter and Retry. Find out more in our https://resilience4j.readme.io/docs/getting-started-2[User Guide].

==== CircuitBreaker and Spring Reactor

The following example shows how to decorate a Mono by using the custom Reactor operator.

[source,java]

CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("testName"); Mono.fromCallable(backendService::doSomething) .transformDeferred(CircuitBreakerOperator.of(circuitBreaker))

NOTE: Resilience4j also provides Reactor operators for RateLimiter, Bulkhead, TimeLimiter and Retry. Find out more in our https://resilience4j.readme.io/docs/getting-started-1[User Guide].

[[ratelimiter]] === RateLimiter

The following example shows how to restrict the calling rate of some method to be not higher than 1 request/second.

[source,java]

// Create a custom RateLimiter configuration RateLimiterConfig config = RateLimiterConfig.custom() .timeoutDuration(Duration.ofMillis(100)) .limitRefreshPeriod(Duration.ofSeconds(1)) .limitForPeriod(1) .build(); // Create a RateLimiter RateLimiter rateLimiter = RateLimiter.of("backendName", config);

// Decorate your call to BackendService.doSomething() Supplier restrictedSupplier = RateLimiter .decorateSupplier(rateLimiter, backendService::doSomething);

// First call is successful Try firstTry = Try.ofSupplier(restrictedSupplier); assertThat(firstTry.isSuccess()).isTrue();

// Second call fails, because the call was not permitted Try secondTry = Try.of(restrictedSupplier); assertThat(secondTry.isFailure()).isTrue(); assertThat(secondTry.getCause()).isInstanceOf(RequestNotPermitted.class);

[[bulkhead]] === Bulkhead There are two isolation strategies and bulkhead implementations.

==== SemaphoreBulkhead The following example shows how to decorate a lambda expression with a Bulkhead. A Bulkhead can be used to limit the amount of parallel executions. This bulkhead abstraction should work well across a variety of threading and io models. It is based on a semaphore, and unlike Hystrix, does not provide "shadow" thread pool option.

[source,java]

// Create a custom Bulkhead configuration BulkheadConfig config = BulkheadConfig.custom() .maxConcurrentCalls(150) .maxWaitDuration(100) .build();

Bulkhead bulkhead = Bulkhead.of("backendName", config);

Supplier supplier = Bulkhead .decorateSupplier(bulkhead, backendService::doSomething);

[[threadpoolbulkhead]] ==== ThreadPoolBulkhead The following example shows how to use a lambda expression with a ThreadPoolBulkhead which uses a bounded queue and a fixed thread pool.

[source,java]

// Create a custom ThreadPoolBulkhead configuration ThreadPoolBulkheadConfig config = ThreadPoolBulkheadConfig.custom() .maxThreadPoolSize(10) .coreThreadPoolSize(2) .queueCapacity(20) .build();

ThreadPoolBulkhead bulkhead = ThreadPoolBulkhead.of("backendName", config);

// Decorate or execute immediately a lambda expression with a ThreadPoolBulkhead. Supplier<CompletionStage> supplier = ThreadPoolBulkhead .decorateSupplier(bulkhead, backendService::doSomething);

CompletionStage execution = bulkhead .executeSupplier(backendService::doSomething);

[[events]] == Consume emitted events

CircuitBreaker, RateLimiter, Cache, Bulkhead, TimeLimiter and Retry components emit a stream of events. It can be consumed for logging, assertions and any other purpose.

=== Examples

A CircuitBreakerEvent can be a state transition, a circuit breaker reset, a successful call, a recorded error or an ignored error. All events contains additional information like event creation time and processing duration of the call. If you want to consume events, you have to register an event consumer.

[source,java]

circuitBreaker.getEventPublisher() .onSuccess(event -> logger.info(...)) .onError(event -> logger.info(...)) .onIgnoredError(event -> logger.info(...)) .onReset(event -> logger.info(...)) .onStateTransition(event -> logger.info(...)); // Or if you want to register a consumer listening to all events, you can do: circuitBreaker.getEventPublisher() .onEvent(event -> logger.info(...));

You can use RxJava or Spring Reactor Adapters to convert the EventPublisher into a Reactive Stream. The advantage of a Reactive Stream is that you can use RxJava's observeOn operator to specify a different Scheduler that the CircuitBreaker will use to send notifications to its observers/consumers.

[source,java]

RxJava2Adapter.toFlowable(circuitBreaker.getEventPublisher()) .filter(event -> event.getEventType() == Type.ERROR) .cast(CircuitBreakerOnErrorEvent.class) .subscribe(event -> logger.info(...))

NOTE: You can also consume events from other components. Find out more in our https://resilience4j.readme.io/[User Guide].

== Talks

[cols="4*"] |===

|0:34 |https://www.youtube.com/watch?v=kR2sm1zelI4[Battle of the Circuit Breakers: Resilience4J vs Istio] |Nicolas Frankel |GOTO Berlin

|0:33 |https://www.youtube.com/watch?v=AwcjOhD91Q0[Battle of the Circuit Breakers: Istio vs. Hystrix/Resilience4J] |Nicolas Frankel |JFuture

|0:42 |https://www.youtube.com/watch?v=KosSsZEqS-k&t=157[Resilience patterns in the post-Hystrix world] |Tomasz Skowroński |Cloud Native Warsaw

|0:52 |https://www.youtube.com/watch?v=NHVxrLb3jFI[Building Robust and Resilient Apps Using Spring Boot and Resilience4j] |David Caron |SpringOne

|0:22 |https://www.youtube.com/watch?v=gvDvOWtPLVY&t=140[Hystrix is dead, now what?] |Tomasz Skowroński |DevoxxPL

|===

== Companies that use Resilience4j

• Deutsche Telekom (In an application with over 400 million requests per day)
• AOL (In an application with low latency requirements)
• Netpulse (In a system with 40+ integrations)
• wescale.de (In a B2B integration platform)
• Topia (In an HR application built with microservices architecture)
• Auto Trader Group plc (The largest Britain digital automotive marketplace)
• PlayStation Network (A platform backend)
• TUI InfoTec GmbH (Backend applications inside of reservation booking workflow streams for accommodations)

== License

Copyright 2020 Robert Winkler, Bohdan Storozhuk, Mahmoud Romeh, Dan Maas and others

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.