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 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 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 BiFunction<? super K,? super V,? extends V> computeFunc)
    Computes a new value for a specific key, if a mapping already existed.
    default void
    forEach(@NotNull BiConsumer<? super K,? super V> action)
    Performs the specified action upon all entries within the cache.
    V
    get(K key)
    Obtains the value associated with the specified key.
    default V
    getOrDefault(K key, V defaultValue)
    Obtains the value associated with the specified key, or the passed default value if no mapping existed.
    V
    merge(K key, V value, @NotNull 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 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:
      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:
      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:
      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 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:
      NullPointerException - if the specified key is null or the compute function is null
      Implementation Note:
      atomicity is dependent on provider characteristics

    • computeIfAbsent

      V computeIfAbsent(@NotNull K key, @NotNull @NotNull 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:
      NullPointerException - if the specified key is null or the compute function is null

    • computeIfPresent

      @Nullable V computeIfPresent(@NotNull K key, @NotNull @NotNull 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:
      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:
      NullPointerException - if the specified key or value is null

    • merge

      V merge(@NotNull K key, @NotNull V value, @NotNull @NotNull 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:
      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:
      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:
      NullPointerException - if a specified key or newValue is null

    • getOrDefault

      @NotNull default V getOrDefault(@NotNull K key, @NotNull V defaultValue)
      Obtains the value associated with the specified key, or the passed default value if no mapping existed.

      Note: Unlike computeIfAbsent(Object, Function), this method does not write the default value to the cache.

      Parameters:
      key - the key whose mapped value should be queried
      defaultValue - the default value to return if no mapping exists for the specified key
      Returns:
      the value mapped to the specified key, if present; otherwise, the specified default value
      Throws:
      NullPointerException - if the specified key is null

    • putAll

      default void putAll(@NotNull @NotNull 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:
      NullPointerException - if the map is null, or the specified map contains null keys or values
      Implementation Note:
      There is no behavior guarantee when there are concurrent updates to the map

    • forEach

      @Experimental default void forEach(@NotNull @NotNull BiConsumer<? super K,? super V> action)
      Performs the specified action upon all entries within the cache.
      Parameters:
      action - the action to perform upon each entry
      Throws:
      NullPointerException - if the specified action is null
      UnsupportedOperationException - if the underlying cache provider does not support iteration over entries
      API Note:
      While this method is technically optional, all of the canonical implementations provided by Xanthic support this operation.
      Implementation Requirements:
      The iteration order of entries is not consistent (across cache different implementations), and should not be relied upon. Iteration may terminate early if the action yields an exception.
      Implementation Note:
      This can be an inefficient operation that ought to be avoided; perhaps your data can be modeled differently to avoid this operation.