Package org.dataloader

Interface CacheMap<K,V>

Type Parameters:
K - type parameter indicating the type of the cache keys
V - type parameter indicating the type of the data that is cached
All Known Implementing Classes:
DefaultCacheMap
@PublicSpi @NullMarked public interface CacheMap<K,V>
CacheMap is used by data loaders that use caching promises to values aka CompletableFuture<V>. A better name for this class might have been FutureCache but that is history now.

The default implementation used by the data loader is based on a ConcurrentHashMap because the data loader code requires the cache to prove atomic writes especially the putIfAbsentAtomically(Object, CompletableFuture) method.

The data loader code using a Compare and Swap (CAS) algorithm to decide if a cache entry is present or not. If you write your own CacheMap implementation then you MUST provide atomic writes in this method to ensure that the same promise for a key is returned always.

This is really a cache of completed CompletableFuture<V> 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 {ValueCache} which is designed for external cache access.

  • Method Details

    • simpleMap

      static <K, V> CacheMap<K,V> simpleMap()
      Creates a new cache map, using the default implementation that is based on a LinkedHashMap.
      Type Parameters:
      K - type parameter indicating the type of the cache keys
      V - type parameter indicating the type of the data that is cached
      Returns:
      the cache map

    • containsKey

      boolean containsKey(K key)
      Checks whether the specified key is contained in the cache map.
      Parameters:
      key - the key to check
      Returns:
      true if the cache contains the key, false otherwise

    • get

      @Nullable CompletableFuture<V> get(K key)
      Gets the specified key from the cache map.

      May throw an exception if the key does not exist, depending on the cache map implementation that is used.

      Parameters:
      key - the key to retrieve
      Returns:
      the cached value, or null if not found (depends on cache implementation)

    • getAll

      Collection<CompletableFuture<V>> getAll()
      Gets a collection of CompletableFutures from the cache map.
      Returns:
      the collection of cached values

    • putIfAbsentAtomically

      @Nullable CompletableFuture<V> putIfAbsentAtomically(K key, CompletableFuture<V> value)
      Atomically creates a new cache map entry with the specified key and value, or updates the value if the key already exists.

      The data loader code using a Compare and Swap (CAS) algorithm to decide if a cache entry is present or not. If you write your own CacheMap implementation then you MUST provide atomic writes in this method to ensure that the same promise for a key is returned always.

      The default implementation of this method uses ConcurrentHashMap has its implementation so these CAS writes work as expected.

      Parameters:
      key - the key to cache
      value - the value to cache
      Returns:
      atomically the previous value for the key or null if the value is not present.

    • delete

      CacheMap<K,V> delete(K key)
      Deletes the entry with the specified key from the cache map, if it exists.
      Parameters:
      key - the key to delete
      Returns:
      the cache map for fluent coding

    • clear

      CacheMap<K,V> clear()
      Clears all entries of the cache map
      Returns:
      the cache map for fluent coding

    • size

      int size()
      Returns the current size of the cache. This is not used by DataLoader directly and intended for testing and debugging. If a cache doesn't support it, it can throw an Exception.
      Returns:
      the size of the cache