Improve hibernate example and add resilience example using failsafe

.github/workflows/examples.yml

@@ -101,9 +101,12 @@ jobs:
       - name: Coalescing Bulkloader
         working-directory: examples/coalescing-bulkloader
         run: ./mvnw test
-      - name: Hibernate JCache
+      - name: Hibernate (jcache)
         working-directory: examples/hibernate
         run: ./gradlew build
+      - name: Resilience (failsafe)
+        working-directory: examples/resilience-failsafe
+        run: ./gradlew build
       - name: Prepare for Graal Native Image
         uses: ./.github/actions/run-gradle
         with:

examples/hibernate/README.md

@@ -1,4 +1,4 @@
-The [Hibernate ORM] can be configured to use a [second-level cache] to reduce the number of accesses
+[Hibernate] can be configured to use a [second-level cache] to reduce the number of accesses
 to the database by caching data in memory to be shared between sessions.
 
 In [hibernate.conf](src/main/resources/hibernate.properties) specify the JCache provider and enable
@@ -29,6 +29,14 @@ caffeine.jcache {
 }
 ```
 
+Enable caching on the entity.
+
+```java
+@Entity
+@Cache(usage = READ_WRITE)
+public class User { ... }
+```
+
 Hibernate will then manage the cache to transparently avoid database calls.
 
 ```java

examples/hibernate/build.gradle.kts

@@ -5,8 +5,8 @@ plugins {
 
 dependencies {
   implementation(libs.bundles.hibernate)
+  implementation(libs.bundles.log4j2)
   implementation(libs.caffeine)
-  implementation(libs.slf4j)
   runtimeOnly(libs.h2)
 
   testImplementation(libs.junit)

examples/hibernate/gradle/libs.versions.toml

@@ -3,6 +3,7 @@ caffeine = "3.1.7"
 h2 = "2.2.220"
 hibernate = "6.3.0.CR1"
 junit = "5.10.0"
+log4j2 = "2.20.0"
 slf4j = "2.0.7"
 truth = "1.1.5"
 versions = "0.47.0"
@@ -14,11 +15,13 @@ hibernate-core = { module = "org.hibernate.orm:hibernate-core", version.ref = "h
 hibernate-jcache = { module = "org.hibernate.orm:hibernate-jcache", version.ref = "hibernate" }
 hibernate-hikaricp = { module = "org.hibernate.orm:hibernate-hikaricp", version.ref = "hibernate" }
 junit = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
-slf4j = { module = "org.slf4j:slf4j-jdk14", version.ref = "slf4j" }
+log4j2-core = { module = "org.apache.logging.log4j:log4j-core", version.ref = "log4j2" }
+log4j2-slf4j = { module = "org.apache.logging.log4j:log4j-slf4j-impl", version.ref = "log4j2" }
 truth = { module = "com.google.truth:truth", version.ref = "truth" }
 
 [bundles]
 hibernate = ["hibernate-core", "hibernate-jcache", "hibernate-hikaricp"]
+log4j2 = ["log4j2-core", "log4j2-slf4j"]
 
 [plugins]
 versions = { id = "com.github.ben-manes.versions", version.ref = "versions" }

examples/hibernate/src/main/java/com/github/benmanes/caffeine/examples/hibernate/Project.java

@@ -15,13 +15,10 @@
  */
 package com.github.benmanes.caffeine.examples.hibernate;
 
-import static jakarta.persistence.AccessType.FIELD;
 import static org.hibernate.annotations.CacheConcurrencyStrategy.READ_WRITE;
 
 import org.hibernate.annotations.Cache;
 
-import jakarta.persistence.Access;
-import jakarta.persistence.Cacheable;
 import jakarta.persistence.Entity;
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.Id;
@@ -31,8 +28,6 @@
  * @author [email protected] (Ben Manes)
  */
 @Entity
-@Cacheable
-@Access(FIELD)
 @Cache(usage = READ_WRITE)
 public class Project {
 

examples/hibernate/src/main/java/com/github/benmanes/caffeine/examples/hibernate/Skill.java

@@ -15,13 +15,10 @@
  */
 package com.github.benmanes.caffeine.examples.hibernate;
 
-import static jakarta.persistence.AccessType.FIELD;
 import static org.hibernate.annotations.CacheConcurrencyStrategy.READ_WRITE;
 
 import org.hibernate.annotations.Cache;
 
-import jakarta.persistence.Access;
-import jakarta.persistence.Cacheable;
 import jakarta.persistence.Entity;
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.Id;
@@ -30,8 +27,6 @@
  * @author [email protected] (Ben Manes)
  */
 @Entity
-@Cacheable
-@Access(FIELD)
 @Cache(usage = READ_WRITE)
 public class Skill {
   @Id

examples/hibernate/src/main/java/com/github/benmanes/caffeine/examples/hibernate/User.java

@@ -15,16 +15,13 @@
  */
 package com.github.benmanes.caffeine.examples.hibernate;
 
-import static jakarta.persistence.AccessType.FIELD;
 import static org.hibernate.annotations.CacheConcurrencyStrategy.READ_WRITE;
 
 import java.util.ArrayList;
 import java.util.List;
 
 import org.hibernate.annotations.Cache;
 
-import jakarta.persistence.Access;
-import jakarta.persistence.Cacheable;
 import jakarta.persistence.Entity;
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.Id;
@@ -35,8 +32,6 @@
  * @author [email protected] (Ben Manes)
  */
 @Entity
-@Cacheable
-@Access(FIELD)
 @Cache(usage = READ_WRITE)
 public class User {
   @Id

examples/hibernate/src/main/resources/hibernate.properties

@@ -1,12 +1,9 @@
-hibernate.dialect=org.hibernate.dialect.H2Dialect
-
-hibernate.connection.provider_class=org.hibernate.hikaricp.internal.HikariCPConnectionProvider
-hibernate.connection.driver_class=org.h2.Driver
 hibernate.connection.url=jdbc:h2:mem:test
 hibernate.connection.username=sa
 
 hibernate.show_sql=false
-hibernate.format_sql=true
+hibernate.format_sql=false
+hibernate.highlight_sql=true
 hibernate.globally_quoted_identifiers=true
 
 hibernate.hbm2ddl.auto=create-drop

examples/hibernate/src/main/resources/log4j2.properties

@@ -0,0 +1,14 @@
+rootLogger.level = info
+rootLogger.appenderRefs = console
+rootLogger.appenderRef.console.ref = console
+
+logger.hibernate.name = org.hibernate
+logger.hibernate.level = warn
+
+logger.hikaricp.name = com.zaxxer.hikari
+logger.hikaricp.level = warn
+
+appender.console.name = console
+appender.console.type = Console
+appender.console.layout.type = PatternLayout
+appender.console.layout.pattern = %highlight{[%p]} %c %m%n

examples/hibernate/src/test/java/com/github/benmanes/caffeine/examples/hibernate/HibernateCacheTest.java

@@ -17,9 +17,6 @@
 
 import static com.github.benmanes.caffeine.examples.hibernate.HibernateSubject.assertThat;
 
-import java.util.logging.Level;
-import java.util.logging.Logger;
-
 import org.hibernate.SessionFactory;
 import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
 import org.hibernate.cfg.Configuration;
@@ -36,7 +33,6 @@ public final class HibernateCacheTest {
 
   @BeforeEach
   public void beforeEach() {
-    Logger.getLogger("").setLevel(Level.WARNING);
     sessionFactory = new Configuration().addAnnotatedClass(User.class)
         .addAnnotatedClass(Skill.class).addAnnotatedClass(Project.class)
         .buildSessionFactory(new StandardServiceRegistryBuilder().build());

examples/resilience-failsafe/README.md

@@ -0,0 +1,57 @@
+[Failsafe's][failsafe] retry, timeout, and fallback strategies can be used to make the cache
+operations resiliant to intermittent failures.
+
+### Retry
+A [retry policy][retry] will retry failed executions a certain number of times, with an optional
+delay between attempts.
+
+```java
+var retryPolicy = RetryPolicy.builder()
+    .withDelay(Duration.ofSeconds(1))
+    .withMaxAttempts(3)
+    .build();
+var failsafe = Failsafe.with(retryPolicy);
+
+// Retry outside of the cache loader for synchronous calls
+Cache<Integer, String> cache = Caffeine.newBuilder().build();
+failsafe.get(() -> cache.get(key, key -> /* intermittent failures */ ));
+
+// Optionally, retry inside the cache load for asynchronous calls
+AsyncCache<Integer, String> asyncCache = Caffeine.newBuilder().buildAsync();
+asyncCache.get(key, (key, executor) -> failsafe.getAsync(() -> /* intermittent failure */));
+```
+
+### Timeout
+A [timeout policy][timeout] will cancel the execution if it takes too long to complete.
+
+```java
+var retryPolicy = RetryPolicy.builder()
+    .withDelay(Duration.ofSeconds(1))
+    .withMaxAttempts(3)
+    .build();
+var timeout = Timeout.builder(Duration.ofSeconds(1)).withInterrupt().build();
+var failsafe = Failsafe.with(timeout, retryPolicy);
+
+Cache<Integer, String> cache = Caffeine.newBuilder().build();
+failsafe.get(() -> cache.get(key, key -> /* timeout */ ));
+```
+
+### Fallback
+A [fallback policy][fallback] will provide an alternative result for a failed execution.
+
+```java
+var retryPolicy = RetryPolicy.builder()
+    .withDelay(Duration.ofSeconds(1))
+    .withMaxAttempts(3)
+    .build();
+var fallback = Fallback.of(/* fallback */);
+var failsafe = Failsafe.with(fallback, retryPolicy);
+
+Cache<Integer, String> cache = Caffeine.newBuilder().build();
+failsafe.get(() -> cache.get(key, key -> /* failure */ ));
+```
+
+[failsafe]: https://failsafe.dev
+[retry]: https://failsafe.dev/retry
+[timeout]: https://failsafe.dev/timeout
+[fallback]: https://failsafe.dev/fallback

examples/resilience-failsafe/build.gradle.kts

@@ -0,0 +1,25 @@
+plugins {
+  `java-library`
+  alias(libs.plugins.versions)
+}
+
+dependencies {
+  implementation(libs.caffeine)
+  implementation(libs.failsafe)
+
+  testImplementation(libs.junit)
+  testImplementation(libs.truth)
+}
+
+tasks.test {
+  useJUnitPlatform()
+}
+
+java.toolchain.languageVersion = JavaLanguageVersion.of(
+  System.getenv("JAVA_VERSION")?.toIntOrNull() ?: 11)
+
+tasks.withType<JavaCompile>().configureEach {
+  javaCompiler = javaToolchains.compilerFor {
+    languageVersion = java.toolchain.languageVersion
+  }
+}

examples/resilience-failsafe/gradle/libs.versions.toml

@@ -0,0 +1,15 @@
+[versions]
+caffeine = "3.1.7"
+failsafe = "3.3.2"
+junit = "5.10.0"
+truth = "1.1.5"
+versions = "0.47.0"
+
+[libraries]
+caffeine = { module = "com.github.ben-manes.caffeine:caffeine", version.ref = "caffeine" }
+failsafe = { module = "dev.failsafe:failsafe", version.ref = "failsafe" }
+junit = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
+truth = { module = "com.google.truth:truth", version.ref = "truth" }
+
+[plugins]
+versions = { id = "com.github.ben-manes.versions", version.ref = "versions" }

examples/resilience-failsafe/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-rc-3-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists