feat: add Cache#close

api/src/main/java/io/github/xanthic/cache/api/Cache.java

@@ -25,7 +25,7 @@
  * @param <K> The type of keys that form the cache
  * @param <V> The type of values contained in the cache
  */
-public interface Cache<K, V> {
+public interface Cache<K, V> extends AutoCloseable {
 
 	/**
 	 * Obtains the value associated with the specified key.
@@ -194,4 +194,15 @@ default void forEach(@NotNull BiConsumer<? super K, ? super V> action) {
 		throw new UnsupportedOperationException();
 	}
 
+	/**
+	 * {@inheritDoc}
+	 * <p>
+	 * Avoid further usage of the cache once it has been closed;
+	 * some implementations may throw exceptions while others are more tolerant.
+	 */
+	@Override
+	default void close() {
+		this.clear();
+	}
+
 }

core/src/testFixtures/java/io/github/xanthic/cache/core/provider/ProviderTestBase.java

@@ -63,6 +63,8 @@ public void putGetClearTest() {
 		for (int i = 0; i < 4; i++) {
 			Assertions.assertEquals(i, m.get(String.valueOf(i)));
 		}
+
+		cache.close();
 	}
 
 	@Test
@@ -102,6 +104,8 @@ public void computeMergeRemoveTest() {
 
 		Assertions.assertNull(cache.compute("a", (k, v) -> null));
 		Assertions.assertNull(cache.get("a"));
+
+		cache.close();
 	}
 
 	@Test
@@ -133,6 +137,8 @@ public void replaceTest() {
 
 		Assertions.assertFalse(cache.replace("9", -9));
 		Assertions.assertNull(cache.get("9"));
+
+		cache.close();
 	}
 
 	@Test
@@ -157,6 +163,7 @@ public void iterateTest() {
 		expected.put("2", 2);
 
 		Assertions.assertEquals(expected, observed);
+		cache.close();
 	}
 
 	@Test
@@ -166,6 +173,7 @@ public void zeroMaxSizeTest() {
 		cache.put("1", 1);
 		Assertions.assertNull(cache.get("1"));
 		Assertions.assertEquals(0, cache.size());
+		cache.close();
 	}
 
 	@Test
@@ -175,6 +183,7 @@ public void zeroExpiryTimeTest() {
 		cache.put("1", 1);
 		Assertions.assertNull(cache.get("1"));
 		Assertions.assertEquals(0, cache.size());
+		cache.close();
 	}
 
 	@Test
@@ -200,6 +209,8 @@ public void sizeEvictionTest() {
 		for (int i = 1; i < 5; i++) {
 			Assertions.assertEquals(i, cache.get(String.valueOf(i)));
 		}
+
+		cache.close();
 	}
 
 	@Test
@@ -227,6 +238,7 @@ public void sizeEvictionListenerTest() {
 
 		// Ensure listener is called the appropriate number of times
 		await().atMost(30, TimeUnit.SECONDS).until(() -> removals.get() == expectedEvictions);
+		cache.close();
 	}
 
 	@Test
@@ -250,6 +262,8 @@ public void timeEvictionTest() {
 		await().atLeast(expiry * 3 / 4, TimeUnit.MILLISECONDS)
 			.atMost(90, TimeUnit.SECONDS)
 			.until(() -> cache.size() == 0);
+
+		cache.close();
 	}
 
 	@Test
@@ -280,6 +294,8 @@ public void timeEvictionListenerTest() {
 		await().atLeast(expiry * 3 / 4, TimeUnit.MILLISECONDS)
 			.atMost(90, TimeUnit.SECONDS)
 			.until(() -> evictions.get() == n);
+
+		cache.close();
 	}
 
 	@Test
@@ -310,6 +326,7 @@ public void replacedListenerTest() {
 
 		// Ensure listener was called the appropriate number of times
 		await().atMost(30, TimeUnit.SECONDS).until(() -> replacements.get() == n);
+		cache.close();
 	}
 
 	@Test
@@ -340,6 +357,7 @@ public void manualRemovalListenerTest() {
 
 		// Ensure listener was called the appropriate number of times
 		await().atMost(90, TimeUnit.SECONDS).until(() -> removals.get() == n);
+		cache.close();
 	}
 
 	@Test
@@ -351,12 +369,8 @@ public void registeredAsDefaultTest() {
 	@Test
 	@DisplayName("Test whether cache can be built with contention flag and custom executor")
 	public void buildTest() {
-		Assertions.assertNotNull(
-			build(spec -> spec.highContention(true).maxSize(null))
-		);
-		Assertions.assertNotNull(
-			build(spec -> spec.highContention(true).executor(Executors.newSingleThreadScheduledExecutor()))
-		);
+		build(spec -> spec.highContention(true).maxSize(null)).close();
+		build(spec -> spec.highContention(true).executor(Executors.newSingleThreadScheduledExecutor())).close();
 	}
 
 	protected <K, V> Cache<K, V> build(Consumer<CacheApiSpec<K, V>> additionalSpec) {

provider-androidx/src/main/java/io/github/xanthic/cache/provider/androidx/AndroidLruProvider.java

@@ -31,8 +31,16 @@ public <K, V> Cache<K, V> build(ICacheSpec<K, V> spec) {
 		Duration expiryTime = spec.expiryTime();
 		if (executor == null) handleUnsupportedExpiry(expiryTime);
 		if (expiryTime == null) return new LruDelegate<>(buildSimple(spec.maxSize(), spec.removalListener()));
-		ScheduledExecutorService exec = executor != null ? executor : Executors.newSingleThreadScheduledExecutor();
-		return new ExpiringLruDelegate<>(spec.maxSize(), spec.removalListener(), expiryTime.toNanos(), getExpiryType(spec.expiryType()), exec);
+		ScheduledExecutorService exec;
+		boolean createdExecutor;
+        if (executor != null) {
+            exec = executor;
+			createdExecutor = false;
+        } else {
+            exec = Executors.newSingleThreadScheduledExecutor();
+			createdExecutor = true;
+        }
+        return new ExpiringLruDelegate<>(spec.maxSize(), spec.removalListener(), expiryTime.toNanos(), getExpiryType(spec.expiryType()), exec, createdExecutor);
 	}
 
 	private static <K, V> LruCache<K, V> buildSimple(Long maxSize, RemovalListener<K, V> listener) {

provider-androidx/src/main/java/io/github/xanthic/cache/provider/androidx/ExpiringLruDelegate.java

@@ -36,6 +36,8 @@ class ExpiringLruDelegate<K, V> extends AbstractCache<K, V> {
 	@EqualsAndHashCode.Exclude
 	ScheduledExecutorService exec;
 	@EqualsAndHashCode.Exclude
+	boolean shouldCloseExecutor;
+	@EqualsAndHashCode.Exclude
 	Map<Map.Entry<K, V>, Future<?>> tracker = new ConcurrentHashMap<>();
 
 	LruCache<K, V> cache = new LruCache<K, V>(getMaxSize() != null ? getMaxSize().intValue() : Integer.MAX_VALUE) {
@@ -97,6 +99,14 @@ public void clear() {
 		}
 	}
 
+	@Override
+	public void close() {
+		super.close();
+		if (shouldCloseExecutor) {
+			this.exec.shutdownNow();
+		}
+	}
+
 	@Override
 	public long size() {
 		return cache.size();

provider-cache2k/src/main/java/io/github/xanthic/cache/provider/cache2k/Cache2kDelegate.java

@@ -40,6 +40,12 @@ public void clear() {
 		cache.clear();
 	}
 
+	@Override
+	public void close() {
+		super.close();
+		cache.close();
+	}
+
 	@Override
 	public V computeIfAbsent(@NotNull K key, @NotNull Function<K, V> computeFunc) {
 		return cache.computeIfAbsent(key, computeFunc);

provider-caffeine/src/main/java/io/github/xanthic/cache/provider/caffeine/CaffeineDelegate.java

@@ -34,6 +34,12 @@ public void clear() {
 		cache.invalidateAll();
 	}
 
+	@Override
+	public void close() {
+		cache.invalidateAll();
+		cache.cleanUp();
+	}
+
 	@Override
 	public long size() {
 		cache.cleanUp();

provider-caffeine3/src/main/java/io/github/xanthic/cache/provider/caffeine3/Caffeine3Delegate.java

@@ -34,6 +34,12 @@ public void clear() {
 		cache.invalidateAll();
 	}
 
+	@Override
+	public void close() {
+		cache.invalidateAll();
+		cache.cleanUp();
+	}
+
 	@Override
 	public long size() {
 		cache.cleanUp();

provider-guava/src/main/java/io/github/xanthic/cache/provider/guava/GuavaDelegate.java

@@ -36,6 +36,12 @@ public void clear() {
 		cache.invalidateAll();
 	}
 
+	@Override
+	public void close() {
+		cache.invalidateAll();
+		cache.cleanUp();
+	}
+
 	@Override
 	public long size() {
 		cache.cleanUp();

provider-infinispan-java11/src/main/java/io/github/xanthic/cache/provider/infinispanjdk11/InfinispanDelegate.java

@@ -34,6 +34,12 @@ public void clear() {
 		cache.clear();
 	}
 
+	@Override
+	public void close() {
+		cache.clear();
+		cache.shutdown();
+	}
+
 	@Override
 	public long size() {
 		return cache.size();

provider-infinispan/src/main/java/io/github/xanthic/cache/provider/infinispan/InfinispanDelegate.java

@@ -34,6 +34,12 @@ public void clear() {
 		cache.clear();
 	}
 
+	@Override
+	public void close() {
+		cache.clear();
+		cache.shutdown();
+	}
+
 	@Override
 	public long size() {
 		return cache.size();