Interface AsyncLoadingCache<K,V>

Type Parameters:
K - the type of keys maintained by this cache
V - the type of mapped values
All Superinterfaces:
AsyncCache<K,V>
All Known Implementing Classes:
BoundedLocalCache.BoundedLocalAsyncLoadingCache, LocalAsyncLoadingCache, UnboundedLocalCache.UnboundedLocalAsyncLoadingCache

public interface AsyncLoadingCache<K,V> extends AsyncCache<K,V>
A semi-persistent mapping from keys to values. Values are automatically loaded by the cache asynchronously, and are stored in the cache until either evicted or manually invalidated.

Implementations of this interface are expected to be thread-safe, and can be safely accessed by multiple concurrent threads.

  • Method Details

    • get

      @NonNull CompletableFuture<V> get(@NonNull K key)
      Returns the future associated with key in this cache, obtaining that value from AsyncCacheLoader.asyncLoad(K, java.util.concurrent.Executor) if necessary. If the asynchronous computation fails, the entry will be automatically removed from this cache.

      If the specified key is not already associated with a value, attempts to compute its value asynchronously and enters it into this cache unless null. The entire method invocation is performed atomically, so the function is applied at most once per key.

      Parameters:
      key - key with which the specified value is to be associated
      Returns:
      the current (existing or computed) future value associated with the specified key
      Throws:
      NullPointerException - if the specified key is null or if the future returned by the AsyncCacheLoader is null
      RuntimeException - or Error if the AsyncCacheLoader does when constructing the future, in which case the mapping is left unestablished
    • getAll

      @NonNull CompletableFuture<Map<K,V>> getAll(@NonNull Iterable<? extends @NonNull K> keys)
      Returns the future of a map of the values associated with keys, creating or retrieving those values if necessary. The returned map contains entries that were already cached, combined with newly loaded entries; it will never contain null keys or values. If the any of the asynchronous computations fail, those entries will be automatically removed from this cache.

      Caches loaded by a AsyncCacheLoader supporting bulk loading will issue a single request to AsyncCacheLoader.asyncLoadAll(java.lang.Iterable<? extends K>, java.util.concurrent.Executor) for all keys which are not already present in the cache. If another call to get(K) tries to load the value for a key in keys, that thread retrieves a future that is completed by this bulk computation. Caches that do not use a AsyncCacheLoader with an optimized bulk load implementation will sequentially load each key by making individual AsyncCacheLoader.asyncLoad(K, java.util.concurrent.Executor) calls. Note that multiple threads can concurrently load values for distinct keys.

      Note that duplicate elements in keys, as determined by Object.equals(java.lang.Object), will be ignored.

      Parameters:
      keys - the keys whose associated values are to be returned
      Returns:
      the future containing an unmodifiable mapping of keys to values for the specified keys in this cache
      Throws:
      NullPointerException - if the specified collection is null or contains a null element, or if the future returned by the AsyncCacheLoader is null
      RuntimeException - or Error if the AsyncCacheLoader does so, if AsyncCacheLoader.asyncLoadAll(java.lang.Iterable<? extends K>, java.util.concurrent.Executor) returns null, or fails when constructing the future, in which case the mapping is left unestablished
    • asMap

      default @NonNull ConcurrentMap<@NonNull K,@NonNull CompletableFuture<V>> asMap()
      Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to the map directly affect the cache.

      Iterators from the returned map are at least weakly consistent: they are safe for concurrent use, but if the cache is modified (including by eviction) after the iterator is created, it is undefined which of the changes (if any) will be reflected in that iterator.

      Specified by:
      asMap in interface AsyncCache<K,V>
      Returns:
      a thread-safe view of this cache supporting all of the optional Map operations
    • synchronous

      @NonNull LoadingCache<K,V> synchronous()
      Returns a view of the entries stored in this cache as a synchronous LoadingCache. A mapping is not present if the value is currently being loaded. Modifications made to the synchronous cache directly affect the asynchronous cache. If a modification is made to a mapping that is currently loading, the operation blocks until the computation completes.
      Specified by:
      synchronous in interface AsyncCache<K,V>
      Returns:
      a thread-safe synchronous view of this cache