feat(api): add forEach method to Cache interface (#171)

Author: iProdigy

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

@@ -1,9 +1,11 @@
 package io.github.xanthic.cache.api;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.Map;
+import java.util.function.BiConsumer;
 import java.util.function.BiFunction;
 import java.util.function.Function;
 
@@ -174,4 +176,22 @@ default void putAll(@NotNull Map<? extends K, ? extends V> map) {
 		map.forEach(this::put);
 	}
 
+	/**
+	 * Performs the specified action upon all entries within the cache.
+	 *
+	 * @param action the action to perform upon each entry
+	 * @apiNote While this method is technically optional, all of the canonical
+	 * implementations provided by Xanthic support this operation.
+	 * @implSpec The iteration order of entries is not consistent (across cache different implementations),
+	 * and should not be relied upon. Iteration may terminate early if the action yields an exception.
+	 * @implNote This can be an inefficient operation that ought to be avoided;
+	 * perhaps your data can be modeled differently to avoid this operation.
+	 * @throws NullPointerException if the specified action is null
+	 * @throws UnsupportedOperationException if the underlying cache provider does not support iteration over entries
+	 */
+	@ApiStatus.Experimental
+	default void forEach(@NotNull BiConsumer<? super K, ? super V> action) {
+		throw new UnsupportedOperationException();
+	}
+
 }

core/src/main/java/io/github/xanthic/cache/core/delegate/EmptyCache.java

@@ -6,6 +6,7 @@
 import org.jetbrains.annotations.Nullable;
 
 import java.util.Map;
+import java.util.function.BiConsumer;
 import java.util.function.BiFunction;
 import java.util.function.Function;
 
@@ -94,4 +95,8 @@ public void putAll(@NotNull Map<? extends K, ? extends V> map) {
 		// no-op
 	}
 
+	@Override
+	public void forEach(@NotNull BiConsumer<? super K, ? super V> action) {
+		// no-op
+	}
 }

core/src/main/java/io/github/xanthic/cache/core/delegate/GenericMapCacheDelegate.java

@@ -8,6 +8,7 @@
 import org.jetbrains.annotations.Nullable;
 
 import java.util.Map;
+import java.util.function.BiConsumer;
 import java.util.function.BiFunction;
 import java.util.function.Function;
 
@@ -88,4 +89,9 @@ public boolean replace(@NotNull K key, @NotNull V oldValue, @NotNull V newValue)
 	public void putAll(@NotNull Map<? extends K, ? extends V> map) {
 		this.map.putAll(map);
 	}
+
+	@Override
+	public void forEach(@NotNull BiConsumer<? super K, ? super V> action) {
+		this.map.forEach(action);
+	}
 }

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

@@ -135,6 +135,30 @@ public void replaceTest() {
 		Assertions.assertNull(cache.get("9"));
 	}
 
+	@Test
+	@DisplayName("Tests cache forEach")
+	public void iterateTest() {
+		// Build cache
+		Cache<String, Integer> cache = build(null);
+
+		// Add entries
+		for (int i = 0; i < 3; i++) {
+			cache.put(String.valueOf(i), i);
+		}
+
+		// Save output of forEach
+		Map<String, Integer> observed = new HashMap<>();
+		cache.forEach(observed::put);
+
+		// Test that observed contents match expected
+		Map<String, Integer> expected = new HashMap<>();
+		expected.put("0", 0);
+		expected.put("1", 1);
+		expected.put("2", 2);
+
+		Assertions.assertEquals(expected, observed);
+	}
+
 	@Test
 	@DisplayName("Test that caches with zero maximum size remain empty")
 	public void zeroMaxSizeTest() {

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

@@ -19,6 +19,7 @@
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiConsumer;
 
 @Value
 @Getter(AccessLevel.PRIVATE)
@@ -101,6 +102,18 @@ public long size() {
 		return cache.size();
 	}
 
+	@Override
+	public void forEach(@NotNull BiConsumer<? super K, ? super V> action) {
+		if (type == ExpiryType.POST_ACCESS) {
+			synchronized (getLock()) {
+				BiConsumer<K, V> markAccessed = this::start;
+				cache.snapshot().forEach(markAccessed.andThen(action));
+			}
+		} else {
+			cache.snapshot().forEach(action);
+		}
+	}
+
 	@NotNull
 	@Override
 	protected Object getLock() {

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

@@ -8,6 +8,8 @@
 import lombok.Value;
 import org.jetbrains.annotations.NotNull;
 
+import java.util.function.BiConsumer;
+
 @Value
 @Getter(AccessLevel.PRIVATE)
 @EqualsAndHashCode(callSuper = false)
@@ -40,6 +42,11 @@ public long size() {
 		return cache.size();
 	}
 
+	@Override
+	public void forEach(@NotNull BiConsumer<? super K, ? super V> action) {
+		cache.snapshot().forEach(action);
+	}
+
 	@NotNull
 	@Override
 	protected Object getLock() {

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

@@ -7,6 +7,7 @@
 import org.jetbrains.annotations.NotNull;
 
 import java.util.Map;
+import java.util.function.BiConsumer;
 import java.util.function.Function;
 
 @Value
@@ -59,4 +60,8 @@ public void putAll(@NotNull Map<? extends K, ? extends V> map) {
 		cache.putAll(map);
 	}
 
+	@Override
+	public void forEach(@NotNull BiConsumer<? super K, ? super V> action) {
+		cache.entries().forEach(e -> action.accept(e.getKey(), e.getValue()));
+	}
 }

provider-ehcache/src/main/java/io/github/xanthic/cache/provider/ehcache/EhcacheDelegate.java

@@ -6,6 +6,7 @@
 import org.jetbrains.annotations.NotNull;
 
 import java.util.Map;
+import java.util.function.BiConsumer;
 
 @Value
 @EqualsAndHashCode(callSuper = false)
@@ -64,4 +65,14 @@ public boolean replace(@NotNull K key, @NotNull V value) {
 	public boolean replace(@NotNull K key, @NotNull V oldValue, @NotNull V newValue) {
 		return read(() -> cache.replace(key, oldValue, newValue));
 	}
+
+	@Override
+	public void forEach(@NotNull BiConsumer<? super K, ? super V> action) {
+		// We can't guarantee that users won't attempt to mutate the cache from within the action
+		// So, we incur a performance penalty to acquire a write (rather than read) lock in order to avoid deadlocking
+		write(() -> {
+			cache.forEach(e -> action.accept((K) e.getKey(), (V) e.getValue()));
+			return Void.TYPE;
+		});
+	}
 }

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

@@ -6,6 +6,7 @@
 import org.jetbrains.annotations.Nullable;
 
 import java.util.Map;
+import java.util.function.BiConsumer;
 import java.util.function.BiFunction;
 import java.util.function.Function;
 
@@ -78,4 +79,9 @@ public boolean replace(@NotNull K key, @NotNull V oldValue, @NotNull V newValue)
 	public void putAll(@NotNull Map<? extends K, ? extends V> map) {
 		cache.putAll(map);
 	}
+
+	@Override
+	public void forEach(@NotNull BiConsumer<? super K, ? super V> action) {
+		cache.forEach(action);
+	}
 }

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

@@ -6,6 +6,7 @@
 import org.jetbrains.annotations.Nullable;
 
 import java.util.Map;
+import java.util.function.BiConsumer;
 import java.util.function.BiFunction;
 import java.util.function.Function;
 
@@ -78,4 +79,9 @@ public boolean replace(@NotNull K key, @NotNull V oldValue, @NotNull V newValue)
 	public void putAll(@NotNull Map<? extends K, ? extends V> map) {
 		cache.putAll(map);
 	}
+
+	@Override
+	public void forEach(@NotNull BiConsumer<? super K, ? super V> action) {
+		cache.forEach(action);
+	}
 }