Interface AsyncCache<K,​V>

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      @NonNull java.util.concurrent.ConcurrentMap<@NonNull K,​@NonNull java.util.concurrent.CompletableFuture<V>> asMap()
      Returns a view of the entries stored in this cache as a thread-safe map.
      @NonNull java.util.concurrent.CompletableFuture<V> get​(@NonNull K key, @NonNull java.util.function.BiFunction<? super K,​java.util.concurrent.Executor,​java.util.concurrent.CompletableFuture<V>> mappingFunction)
      Returns the future associated with key in this cache, obtaining that value from mappingFunction if necessary.
      @NonNull java.util.concurrent.CompletableFuture<V> get​(@NonNull K key, @NonNull java.util.function.Function<? super K,​? extends V> mappingFunction)
      Returns the future associated with key in this cache, obtaining that value from mappingFunction if necessary.
      default @NonNull java.util.concurrent.CompletableFuture<java.util.Map<K,​V>> getAll​(@NonNull java.lang.Iterable<? extends @NonNull K> keys, @NonNull java.util.function.BiFunction<java.lang.Iterable<? extends @NonNull K>,​java.util.concurrent.Executor,​java.util.concurrent.CompletableFuture<java.util.Map<K,​V>>> mappingFunction)
      Returns the future of a map of the values associated with keys, creating or retrieving those values if necessary.
      default @NonNull java.util.concurrent.CompletableFuture<java.util.Map<K,​V>> getAll​(@NonNull java.lang.Iterable<? extends @NonNull K> keys, @NonNull java.util.function.Function<java.lang.Iterable<? extends @NonNull K>,​@NonNull java.util.Map<K,​V>> mappingFunction)
      Returns the future of a map of the values associated with keys, creating or retrieving those values if necessary.
      @Nullable java.util.concurrent.CompletableFuture<V> getIfPresent​(@NonNull java.lang.Object key)
      Returns the future associated with key in this cache, or null if there is no cached future for key.
      void put​(@NonNull K key, @NonNull java.util.concurrent.CompletableFuture<V> valueFuture)
      Associates value with key in this cache.
      @NonNull Cache<K,​V> synchronous()
      Returns a view of the entries stored in this cache as a synchronous Cache.
    • Method Detail

      • getIfPresent

        @Nullable java.util.concurrent.CompletableFuture<V> getIfPresent​(@CompatibleWith("K")
                                                                         @NonNull java.lang.Object key)
        Returns the future associated with key in this cache, or null if there is no cached future for key.
        Parameters:
        key - key whose associated value is to be returned
        Returns:
        the current (existing or computed) future value to which the specified key is mapped, or null if this cache contains no mapping for the key
        Throws:
        java.lang.NullPointerException - if the specified key is null
      • get

        @NonNull java.util.concurrent.CompletableFuture<V> get​(@NonNull K key,
                                                               @NonNull java.util.function.Function<? super K,​? extends V> mappingFunction)
        Returns the future associated with key in this cache, obtaining that value from mappingFunction if necessary. This method provides a simple substitute for the conventional "if cached, return; otherwise create, cache and return" pattern.

        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. If the asynchronous computation fails, the entry will be automatically removed from this cache.

        Warning: as with CacheLoader.load(K), mappingFunction must not attempt to update any other mappings of this cache.

        Parameters:
        key - key with which the specified value is to be associated
        mappingFunction - the function to asynchronously compute a value
        Returns:
        the current (existing or computed) future value associated with the specified key
        Throws:
        java.lang.NullPointerException - if the specified key or mappingFunction is null
      • get

        @NonNull java.util.concurrent.CompletableFuture<V> get​(@NonNull K key,
                                                               @NonNull java.util.function.BiFunction<? super K,​java.util.concurrent.Executor,​java.util.concurrent.CompletableFuture<V>> mappingFunction)
        Returns the future associated with key in this cache, obtaining that value from mappingFunction if necessary. This method provides a simple substitute for the conventional "if cached, return; otherwise create, cache and return" pattern.

        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. If the asynchronous computation fails, the entry will be automatically removed from this cache.

        Warning: as with CacheLoader.load(K), mappingFunction must not attempt to update any other mappings of this cache.

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

        default @NonNull java.util.concurrent.CompletableFuture<java.util.Map<K,​V>> getAll​(@NonNull java.lang.Iterable<? extends @NonNull K> keys,
                                                                                                 @NonNull java.util.function.Function<java.lang.Iterable<? extends @NonNull K>,​@NonNull java.util.Map<K,​V>> mappingFunction)
        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.

        A single request to the mappingFunction is performed for all keys which are not already present in the cache. If another call to get(K, java.util.function.Function<? super K, ? extends V>) tries to load the value for a key in keys, that thread retrieves a future that is completed by this bulk computation. Any loaded values for keys that were not specifically requested will not be returned, but will be stored in the cache. 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
        mappingFunction - the function to asynchronously compute the values
        Returns:
        the future containing an unmodifiable mapping of keys to values for the specified keys in this cache
        Throws:
        java.lang.NullPointerException - if the specified collection is null or contains a null element, or if the future returned by the mappingFunction is null
        java.lang.RuntimeException - or Error if the mappingFunction does so, in which case the mapping is left unestablished
      • getAll

        default @NonNull java.util.concurrent.CompletableFuture<java.util.Map<K,​V>> getAll​(@NonNull java.lang.Iterable<? extends @NonNull K> keys,
                                                                                                 @NonNull java.util.function.BiFunction<java.lang.Iterable<? extends @NonNull K>,​java.util.concurrent.Executor,​java.util.concurrent.CompletableFuture<java.util.Map<K,​V>>> mappingFunction)
        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.

        A single request to the mappingFunction is performed for all keys which are not already present in the cache. If another call to get(K, java.util.function.Function<? super K, ? extends V>) tries to load the value for a key in keys, that thread retrieves a future that is completed by this bulk computation. Any loaded values for keys that were not specifically requested will not be returned, but will be stored in the cache. 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
        mappingFunction - the function to asynchronously compute the values
        Returns:
        the future containing an unmodifiable mapping of keys to values for the specified keys in this cache
        Throws:
        java.lang.NullPointerException - if the specified collection is null or contains a null element, or if the future returned by the mappingFunction is null
        java.lang.RuntimeException - or Error if the mappingFunction does so, in which case the mapping is left unestablished
      • put

        void put​(@NonNull K key,
                 @NonNull java.util.concurrent.CompletableFuture<V> valueFuture)
        Associates value with key in this cache. If the cache previously contained a value associated with key, the old value is replaced by value. If the asynchronous computation fails, the entry will be automatically removed.

        Prefer get(Object, Function) when using the conventional "if cached, return; otherwise create, cache and return" pattern.

        Parameters:
        key - key with which the specified value is to be associated
        valueFuture - value to be associated with the specified key
        Throws:
        java.lang.NullPointerException - if the specified key or value is null
      • asMap

        @NonNull java.util.concurrent.ConcurrentMap<@NonNull K,​@NonNull java.util.concurrent.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.

        A computation operation, such as ConcurrentMap.compute(K, java.util.function.BiFunction<? super K, ? super V, ? extends V>), performs the entire method invocation atomically, so the function is applied at most once per key. Some attempted update operations by other threads may be blocked while computation is in progress. The computation must not attempt to update any other mappings of this 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.

        Returns:
        a thread-safe view of this cache supporting all of the optional Map operations
      • synchronous

        @NonNull Cache<K,​V> synchronous()
        Returns a view of the entries stored in this cache as a synchronous Cache. 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.
        Returns:
        a thread-safe synchronous view of this cache