Package io.github.xanthic.cache.api

Interface Cache<K,​V>

Type Parameters:
K - The type of keys that form the cache
V - The type of values contained in the cache
public interface Cache<K,​V>
The basic interface that various cache implementations must provide.

This interface can be thought as a superset of Map; less functionality is required here to achieve greater compatibility.

There cannot be duplicate keys, and null keys or values are not permitted.

Instances should be thread-safe, but no guarantee is made whether this is achieved through fine-grained locking or blunt synchronization.

Implementations ought to implement expiry and size-based eviction, as defined in ICacheSpec.

  • Method Summary

    Modifier and Type Method Description
    void clear()
    Removes all entries from the cache.
    V compute​(K key, @NotNull java.util.function.BiFunction<? super K,​? super V,​? extends V> computeFunc)
    Computes what value should be associated with the specified key, or null if the mapping should be removed.
    V computeIfAbsent​(K key, @NotNull java.util.function.Function<K,​V> computeFunc)
    Obtains the value currently associated with the specified key, or atomically stores the computed value if no prior mapping existed.
    V computeIfPresent​(K key, @NotNull java.util.function.BiFunction<? super K,​? super V,​? extends V> computeFunc)
    Computes a new value for a specific key, if a mapping already existed.
    V get​(K key)
    Obtains the value associated with the specified key.
    V merge​(K key, V value, @NotNull java.util.function.BiFunction<V,​V,​V> mergeFunc)
    Associates the key with the specified value (or the result of the atomic merge function if a mapping already existed).
    V put​(K key, V value)
    Associates the specified key with the specified value, creating or replacing the mapping as needed.
    default void putAll​(@NotNull java.util.Map<? extends K,​? extends V> map)
    Copies all of the mappings from the specified map to this cache.
    V putIfAbsent​(K key, V value)
    Creates a mapping from the specified key to the specified value, if no mapping for the key already existed.
    V remove​(K key)
    Deletes any mapping that may exist for the specified key.
    boolean replace​(K key, V value)
    Replaces the entry for the specified key only if it is currently mapped to some value.
    boolean replace​(K key, V oldValue, V newValue)
    Replaces the value for the specified key only if it is currently mapped to the specified old value.
    long size()  

  • Method Details

    • get

      @Nullable V get​(@NotNull K key)
      Obtains the value associated with the specified key.
      Parameters:
      key - the key whose mapped value should be queried
      Returns:
      the value associated with the key in the cache, or null if no such mapping was found
      Throws:
      java.lang.NullPointerException - if the specified key is null

    • put

      @Nullable V put​(@NotNull K key, @NotNull V value)
      Associates the specified key with the specified value, creating or replacing the mapping as needed.
      Parameters:
      key - the key whose mapping should be created or updated
      value - the value to be associated with the specified key
      Returns:
      the previous value associated with the key, or null if no prior mapping existed
      Throws:
      java.lang.NullPointerException - if the specified key or value is null

    • remove

      @Nullable V remove​(@NotNull K key)
      Deletes any mapping that may exist for the specified key.
      Parameters:
      key - the key whose mapping should be deleted
      Returns:
      the value in the removed mapping, or null if no mapping existed
      Throws:
      java.lang.NullPointerException - if the specified key is null

    • clear

      void clear()
      Removes all entries from the cache.

    • size

      long size()
      Returns:
      the estimated number of entries contained in the cache

    • compute

      @Nullable V compute​(@NotNull K key, @NotNull @NotNull java.util.function.BiFunction<? super K,​? super V,​? extends V> computeFunc)
      Computes what value should be associated with the specified key, or null if the mapping should be removed.
      Parameters:
      key - the key with which the specified value is to be associated
      computeFunc - the function to compute a value
      Returns:
      the new value associated with the specified key, or null if none
      Throws:
      java.lang.NullPointerException - if the specified key is null or the compute function is null

    • computeIfAbsent

      V computeIfAbsent​(@NotNull K key, @NotNull @NotNull java.util.function.Function<K,​V> computeFunc)
      Obtains the value currently associated with the specified key, or atomically stores the computed value if no prior mapping existed.
      Parameters:
      key - the key whose mapping should be created or returned
      computeFunc - the value supplier for a given key, if no mapping already existed
      Returns:
      the current (existing or computed) value associated with the key
      Throws:
      java.lang.NullPointerException - if the specified key is null or the compute function is null

    • computeIfPresent

      @Nullable V computeIfPresent​(@NotNull K key, @NotNull @NotNull java.util.function.BiFunction<? super K,​? super V,​? extends V> computeFunc)
      Computes a new value for a specific key, if a mapping already existed.

      If the compute function yields null, the mapping should be removed.

      Parameters:
      key - the key whose mapping should be updated
      computeFunc - the function to compute the new value for an already existing mapping
      Returns:
      the new value associated with the key, or null if none
      Throws:
      java.lang.NullPointerException - if the specified key is null or the compute function is null

    • putIfAbsent

      @Nullable V putIfAbsent​(@NotNull K key, @NotNull V value)
      Creates a mapping from the specified key to the specified value, if no mapping for the key already existed.
      Parameters:
      key - the key whose mapping should be created or returned
      value - the value that should be associated with the key if no prior mapping exists
      Returns:
      the previous value associated with the key, or null if no mapping already existed
      Throws:
      java.lang.NullPointerException - if the specified key or value is null

    • merge

      V merge​(@NotNull K key, @NotNull V value, @NotNull @NotNull java.util.function.BiFunction<V,​V,​V> mergeFunc)
      Associates the key with the specified value (or the result of the atomic merge function if a mapping already existed).
      Parameters:
      key - the key whose mapping should be created or updated
      value - the value to be associated with the key or merged with the existing mapped value
      mergeFunc - the function that takes the existing value and the new value to compute a merged value
      Returns:
      the latest value associated with the specified key
      Throws:
      java.lang.NullPointerException - if the specified key or the value or mergeFunc is null

    • replace

      boolean replace​(@NotNull K key, @NotNull V value)
      Replaces the entry for the specified key only if it is currently mapped to some value.
      Parameters:
      key - the key whose mapped value should be updated
      value - the value to be associated with the specified key
      Returns:
      whether a replacement occurred (a prior mapping must have existed to return true)
      Throws:
      java.lang.NullPointerException - if the specified key or value is null

    • replace

      boolean replace​(@NotNull K key, @NotNull V oldValue, @NotNull V newValue)
      Replaces the value for the specified key only if it is currently mapped to the specified old value.
      Parameters:
      key - the key whose mapped value should be updated
      oldValue - the value expected to be already associated with the specified key
      newValue - the value to be newly associated with the specified key
      Returns:
      whether a replacement occurred
      Throws:
      java.lang.NullPointerException - if a specified key or newValue is null

    • putAll

      default void putAll​(@NotNull @NotNull java.util.Map<? extends K,​? extends V> map)
      Copies all of the mappings from the specified map to this cache.
      Parameters:
      map - the map whose entries should be added to this cache
      Throws:
      java.lang.NullPointerException - if the map is null, or the specified map contains null keys or values