A re-work of the #82 that renamed a few things, tested more and fixed a few bugs

Author: bbakerman

build.gradle

@@ -58,6 +58,7 @@ dependencies {
     testCompile 'org.slf4j:slf4j-simple:' + slf4jVersion
     testCompile "junit:junit:4.12"
     testCompile 'org.awaitility:awaitility:2.0.0'
+    testImplementation 'com.github.ben-manes.caffeine:caffeine:2.9.0'
 }
 
 task sourcesJar(type: Jar) {

src/main/java/org/dataloader/CacheMap.java

@@ -28,37 +28,39 @@
  * implementation could also have used a regular {@link java.util.Map} instead of this {@link CacheMap}, but
  * this aligns better to the reference data loader implementation provided by Facebook
  * <p>
- * Also it doesn't require you to implement the full set of map overloads, just the required methods.
+ * This is really a cache of completed {@link CompletableFuture} values in memory.  It is used, when caching is enabled, to
+ * give back the same future to any code that may call it.  if you need a cache of the underlying values that is possible external to the JVM
+ * then you will want to use {{@link CachedValueStore}} which is designed for external cache access.
  *
- * @param <U> type parameter indicating the type of the cache keys
+ * @param <K> type parameter indicating the type of the cache keys
  * @param <V> type parameter indicating the type of the data that is cached
  *
  * @author <a href="https://github.com/aschrijver/">Arnold Schrijver</a>
  * @author <a href="https://github.com/bbakerman/">Brad Baker</a>
  */
 @PublicSpi
-public interface CacheMap<U, V> {
+public interface CacheMap<K, V> {
 
     /**
      * Creates a new cache map, using the default implementation that is based on a {@link java.util.LinkedHashMap}.
      *
-     * @param <U> type parameter indicating the type of the cache keys
+     * @param <K> type parameter indicating the type of the cache keys
      * @param <V> type parameter indicating the type of the data that is cached
      *
      * @return the cache map
      */
-    static <U, V> CacheMap<U, CompletableFuture<V>> simpleMap() {
+    static <K, V> CacheMap<K, V> simpleMap() {
         return new DefaultCacheMap<>();
     }
 
     /**
-     * Checks whether the specified key is contained in the cach map.
+     * Checks whether the specified key is contained in the cache map.
      *
      * @param key the key to check
      *
      * @return {@code true} if the cache contains the key, {@code false} otherwise
      */
-    boolean containsKey(U key);
+    boolean containsKey(K key);
 
     /**
      * Gets the specified key from the cache map.
@@ -70,7 +72,7 @@ static <U, V> CacheMap<U, CompletableFuture<V>> simpleMap() {
      *
      * @return the cached value, or {@code null} if not found (depends on cache implementation)
      */
-    V get(U key);
+    CompletableFuture<V> get(K key);
 
     /**
      * Creates a new cache map entry with the specified key and value, or updates the value if the key already exists.
@@ -80,7 +82,7 @@ static <U, V> CacheMap<U, CompletableFuture<V>> simpleMap() {
      *
      * @return the cache map for fluent coding
      */
-    CacheMap<U, V> set(U key, V value);
+    CacheMap<K, V> set(K key, CompletableFuture<V> value);
 
     /**
      * Deletes the entry with the specified key from the cache map, if it exists.
@@ -89,12 +91,12 @@ static <U, V> CacheMap<U, CompletableFuture<V>> simpleMap() {
      *
      * @return the cache map for fluent coding
      */
-    CacheMap<U, V> delete(U key);
+    CacheMap<K, V> delete(K key);
 
     /**
      * Clears all entries of the cache map
      *
      * @return the cache map for fluent coding
      */
-    CacheMap<U, V> clear();
+    CacheMap<K, V> clear();
 }

src/main/java/org/dataloader/CachedValueStore.java

@@ -0,0 +1,92 @@
+package org.dataloader;
+
+import org.dataloader.annotations.PublicSpi;
+import org.dataloader.impl.DefaultCachedValueStore;
+
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Cache value store for data loaders that use caching and want a long-lived or external cache.
+ * <p>
+ * The default implementation is a no-op store which replies with the key always missing and doesn't
+ * store any actual results. This is to avoid duplicating the stored data between the {@link CacheMap}
+ * and the store.
+ * <p>
+ * The API signature uses completable futures because the backing implementation MAY be a remote external cache
+ * and hence exceptions may happen in retrieving values.
+ *
+ * @param <K> the type of cache keys
+ * @param <V> the type of cache values
+ *
+ * @author <a href="https://github.com/craig-day">Craig Day</a>
+ */
+@PublicSpi
+public interface CachedValueStore<K, V> {
+
+    /**
+     * Creates a new store, using the default no-op implementation.
+     *
+     * @param <K> the type of cache keys
+     * @param <V> the type of cache values
+     *
+     * @return the cache store
+     */
+    static <K, V> CachedValueStore<K, V> defaultStore() {
+        return new DefaultCachedValueStore<>();
+    }
+
+    /**
+     * Checks whether the specified key is contained in the store.
+     * <p>
+     * {@link DataLoader} first calls {@link #containsKey(Object)} and then calls {@link #get(Object)}.  If the
+     * backing cache implementation cannot answer the `containsKey` call then simply return true and the
+     * following `get` call can complete exceptionally to cause the {@link DataLoader}
+     * to enqueue the key to the {@link BatchLoader#load(List)} call since it is not present in cache.
+     *
+     * @param key the key to check if its present in the cache
+     *
+     * @return {@code true} if the cache contains the key, {@code false} otherwise
+     */
+    CompletableFuture<Boolean> containsKey(K key);
+
+    /**
+     * Gets the specified key from the store.
+     *
+     * @param key the key to retrieve
+     *
+     * @return a future containing the cached value (which maybe null) or an exception if the key does
+     * not exist in the cache.
+     *
+     * IMPORTANT: The future may fail if the key does not exist depending on implementation. Implementations should
+     * return an exceptional future if the key is not present in the cache, not null which is a valid value
+     * for a key.
+     */
+    CompletableFuture<V> get(K key);
+
+    /**
+     * Stores the value with the specified key, or updates it if the key already exists.
+     *
+     * @param key   the key to store
+     * @param value the value to store
+     *
+     * @return a future containing the stored value for fluent composition
+     */
+    CompletableFuture<V> set(K key, V value);
+
+    /**
+     * Deletes the entry with the specified key from the store, if it exists.
+     *
+     * @param key the key to delete
+     *
+     * @return a void future for error handling and fluent composition
+     */
+    CompletableFuture<Void> delete(K key);
+
+    /**
+     * Clears all entries from the store.
+     *
+     * @return a void future for error handling and fluent composition
+     */
+    CompletableFuture<Void> clear();
+}

src/main/java/org/dataloader/DataLoader.java

@@ -30,6 +30,7 @@
 import java.util.List;
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
+import java.util.function.BiConsumer;
 
 import static org.dataloader.impl.Assertions.nonNull;
 
@@ -64,8 +65,9 @@
 public class DataLoader<K, V> {
 
     private final DataLoaderHelper<K, V> helper;
-    private final CacheMap<Object, CompletableFuture<V>> futureCache;
     private final StatisticsCollector stats;
+    private final CacheMap<Object, V> futureCache;
+    private final CachedValueStore<Object, V> cachedValueStore;
 
     /**
      * Creates new DataLoader with the specified batch loader function and default options
@@ -414,18 +416,23 @@ public DataLoader(BatchLoader<K, V> batchLoadFunction, DataLoaderOptions options
     DataLoader(Object batchLoadFunction, DataLoaderOptions options, Clock clock) {
         DataLoaderOptions loaderOptions = options == null ? new DataLoaderOptions() : options;
         this.futureCache = determineCacheMap(loaderOptions);
+        this.cachedValueStore = determineCacheStore(loaderOptions);
         // order of keys matter in data loader
         this.stats = nonNull(loaderOptions.getStatisticsCollector());
 
-        this.helper = new DataLoaderHelper<>(this, batchLoadFunction, loaderOptions, this.futureCache, this.stats, clock);
+        this.helper = new DataLoaderHelper<>(this, batchLoadFunction, loaderOptions, this.futureCache, this.cachedValueStore, this.stats, clock);
     }
 
 
     @SuppressWarnings("unchecked")
-    private CacheMap<Object, CompletableFuture<V>> determineCacheMap(DataLoaderOptions loaderOptions) {
-        return loaderOptions.cacheMap().isPresent() ? (CacheMap<Object, CompletableFuture<V>>) loaderOptions.cacheMap().get() : CacheMap.simpleMap();
+    private CacheMap<Object, V> determineCacheMap(DataLoaderOptions loaderOptions) {
+        return (CacheMap<Object, V>) loaderOptions.cacheMap().orElseGet(CacheMap::simpleMap);
     }
 
+    @SuppressWarnings("unchecked")
+    private CachedValueStore<Object, V> determineCacheStore(DataLoaderOptions loaderOptions) {
+        return (CachedValueStore<Object, V>) loaderOptions.cachedValueStore().orElseGet(CachedValueStore::defaultStore);
+    }
 
     /**
      * This returns the last instant the data loader was dispatched.  When the data loader is created this value is set to now.
@@ -628,9 +635,24 @@ public int dispatchDepth() {
      * @return the data loader for fluent coding
      */
     public DataLoader<K, V> clear(K key) {
+        return clear(key, (v, e) -> {
+        });
+    }
+
+    /**
+     * Clears the future with the specified key from the cache remote value store, if caching is enabled
+     * and a remote store is set, so it will be re-fetched and stored on the next load request.
+     *
+     * @param key     the key to remove
+     * @param handler a handler that will be called after the async remote clear completes
+     *
+     * @return the data loader for fluent coding
+     */
+    public DataLoader<K, V> clear(K key, BiConsumer<Void, Throwable> handler) {
         Object cacheKey = getCacheKey(key);
         synchronized (this) {
             futureCache.delete(cacheKey);
+            cachedValueStore.delete(key).whenComplete(handler);
         }
         return this;
     }
@@ -641,14 +663,29 @@ public DataLoader<K, V> clear(K key) {
      * @return the data loader for fluent coding
      */
     public DataLoader<K, V> clearAll() {
+        return clearAll((v, e) -> {
+        });
+    }
+
+    /**
+     * Clears the entire cache map of the loader, and of the cached value store.
+     *
+     * @param handler a handler that will be called after the async remote clear all completes
+     *
+     * @return the data loader for fluent coding
+     */
+    public DataLoader<K, V> clearAll(BiConsumer<Void, Throwable> handler) {
         synchronized (this) {
             futureCache.clear();
+            cachedValueStore.clear().whenComplete(handler);
         }
         return this;
     }
 
     /**
-     * Primes the cache with the given key and value.
+     * Primes the cache with the given key and value.  Note this will only prime the future cache
+     * and not the value store.  Use {@link CachedValueStore#set(Object, Object)} if you want
+     * o prime it with values before use
      *
      * @param key   the key
      * @param value the value