Interface Cache

All Known Implementing Classes:
AdaptiveObjectCache, NoOpCache
public interface Cache
A generic cache interface for storing and managing objects identified by unique keys.

The Cache interface is primarily used by Fluxzero to store entities or other frequently accessed objects.

The interface supports standard cache operations such as put, get, remove, compute, and clear, and also allows for registering eviction listeners to track when items are removed.

Note: All keys and values in this cache are treated as Object; callers are responsible for type safety when retrieving values.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Removes all entries from the cache.
    void
    close()
    Closes the cache and releases all associated resources.
    <T> T
    compute(Object id, BiFunction<? super Object, ? super T, ? extends T> mappingFunction)
    Computes and stores a new value for the given id using the provided function.
    <T> T
    computeIfAbsent(Object id, Function<? super Object, T> mappingFunction)
    If a value is not already associated with the given id, computes and stores one using the given function.
    <T> T
    computeIfPresent(Object id, BiFunction<? super Object, ? super T, ? extends T> mappingFunction)
    If a value is already associated with the given id, computes a new value using the provided function and replaces the old one.
    boolean
    containsKey(Object id)
    Checks whether the cache contains an entry for the given id.
    <T> T
    get(Object id)
    Retrieves the value associated with the given id, or null if not found.
    default <T> T
    getOrDefault(Object id, T defaultValue)
    Retrieves the value associated with the given id, or returns the specified default if not present.
    default boolean
    isEmpty()
    Returns whether the cache is empty.
    default <T> void
    mergeAll(Map<?, ? extends T> values, BiFunction<? super T, ? super T, ? extends T> mergeFunction)
    Merges a bounded group of candidate values into this cache.
    <T> void
    modifyEach(BiFunction<? super Object, ? super T, ? extends T> modifierFunction)
    Applies the given modifier function to all values currently in the cache.
    Object
    put(Object id, Object value)
    Puts a value in the cache for the given id, overwriting any existing value.
    Object
    putIfAbsent(Object id, Object value)
    Associates the specified value with the given id only if no value is currently associated.
    Cache
    rebuild()
    Returns a fresh cache instance with the same configuration and no stored entries.
    Registration
    registerEvictionListener(Consumer<CacheEviction> listener)
    Registers a listener to be notified whenever a cache entry is evicted or removed.
    <T> T
    remove(Object id)
    Removes the entry associated with the given id, if present.
    int
    size()
    Returns the number of entries currently stored in the cache.
    default <U,T> void
    supplyAll(Iterable<? extends U> lookups, Function<? super U, ?> keyFunction, BiConsumer<? super U, ? super T> valueConsumer)
    Supplies every present value from an ordered group of lookups.
    default <U,T> void
    updateAll(Iterable<? extends U> updates, Function<? super U, ?> keyFunction, BiFunction<? super U, ? super T, ? extends T> updateFunction)
    Applies an ordered group of updates while deriving each cache key from the update value.
    default <U,T> void
    updateAll(Iterable<? extends U> updates, Function<? super U, ?> lookupKeyFunction, Function<? super U, ?> retainedKeyFunction, BiFunction<? super U, ? super T, ? extends T> updateFunction)
    Applies an ordered group of updates using a possibly transient lookup key and a stable key for new entries.
    default <T> void
    updateAll(Map<?, ? extends Function<? super T, ? extends T>> updates)
    Applies independent per-key update functions as one bounded cache operation.

  • Method Details

    • put

      Object put(Object id, Object value)
      Puts a value in the cache for the given id, overwriting any existing value.
      Parameters:
      id - the key with which the specified value is to be associated
      value - the value to be associated with the specified key
      Returns:
      the previous value associated with the id, or null if none

    • putIfAbsent

      Object putIfAbsent(Object id, Object value)
      Associates the specified value with the given id only if no value is currently associated.
      Parameters:
      id - the key to check for presence
      value - the value to associate if absent
      Returns:
      the existing value associated with the key, or null if the new value was successfully put

    • computeIfAbsent

      <T> T computeIfAbsent(Object id, Function<? super Object, T> mappingFunction)
      If a value is not already associated with the given id, computes and stores one using the given function.
      Type Parameters:
      T - the expected type of the value
      Parameters:
      id - the key to check or compute
      mappingFunction - the function to compute a value if absent
      Returns:
      the current or newly computed value

    • computeIfPresent

      <T> T computeIfPresent(Object id, BiFunction<? super Object, ? super T, ? extends T> mappingFunction)
      If a value is already associated with the given id, computes a new value using the provided function and replaces the old one.
      Type Parameters:
      T - the expected type of the value
      Parameters:
      id - the key to compute for
      mappingFunction - the function to compute a new value from the current one
      Returns:
      the newly computed value, or null if the mapping function returned null

    • compute

      <T> T compute(Object id, BiFunction<? super Object, ? super T, ? extends T> mappingFunction)
      Computes and stores a new value for the given id using the provided function.

      The previous value (if any) is provided to the function. The result is stored in the cache.

      Type Parameters:
      T - the expected type of the value
      Parameters:
      id - the key to compute for
      mappingFunction - the function to compute a new value
      Returns:
      the newly computed value, or null if the mapping function returned null

    • mergeAll

      default <T> void mergeAll(Map<?, ? extends T> values, BiFunction<? super T, ? super T, ? extends T> mergeFunction)
      Merges a bounded group of candidate values into this cache.

      The default implementation preserves the ordinary per-key compute(Object, BiFunction) contract. Implementations may override this method to reduce lock transitions while retaining the same per-key merge semantics. The group as a whole is not an atomic transaction.

      Type Parameters:
      T - value type
      Parameters:
      values - candidate value by cache key
      mergeFunction - selects the retained value from the current and candidate value

    • updateAll

      default <T> void updateAll(Map<?, ? extends Function<? super T, ? extends T>> updates)
      Applies independent per-key update functions as one bounded cache operation.

      The default implementation preserves the ordinary per-key compute(Object, BiFunction) contract. Implementations may override this method to amortize shared bookkeeping or lock transitions. The group as a whole is not an atomic transaction.

      Type Parameters:
      T - value type
      Parameters:
      updates - update function by cache key

    • updateAll

      default <U,T> void updateAll(Iterable<? extends U> updates, Function<? super U, ?> keyFunction, BiFunction<? super U, ? super T, ? extends T> updateFunction)
      Applies an ordered group of updates while deriving each cache key from the update value.

      Unlike the map-shaped overload, this form permits repeated keys and applies them in iteration order. The default implementation preserves the ordinary per-key compute(Object, BiFunction) contract; implementations may override it to amortize locking and pressure bookkeeping.

      Type Parameters:
      U - update value type
      T - cache value type
      Parameters:
      updates - ordered update values
      keyFunction - derives the cache key for an update
      updateFunction - applies an update to the current cached value

    • updateAll

      default <U,T> void updateAll(Iterable<? extends U> updates, Function<? super U, ?> lookupKeyFunction, Function<? super U, ?> retainedKeyFunction, BiFunction<? super U, ? super T, ? extends T> updateFunction)
      Applies an ordered group of updates using a possibly transient lookup key and a stable key for new entries.

      The default implementation uses only retainedKeyFunction, preserving the ordinary cache contract for custom implementations. Caches that can distinguish lookup from insertion may override this method to avoid allocating a stable key when an existing entry is merely replaced. A lookup key must compare equal to its retained counterpart for the duration of the lookup and must never be retained by an implementation.

      Type Parameters:
      U - update value type
      T - cache value type
      Parameters:
      updates - ordered update values
      lookupKeyFunction - derives a key that may be reused after each lookup
      retainedKeyFunction - derives the stable key to retain when an entry must be inserted
      updateFunction - applies an update to the current cached value

    • modifyEach

      <T> void modifyEach(BiFunction<? super Object, ? super T, ? extends T> modifierFunction)
      Applies the given modifier function to all values currently in the cache.

      This is useful for bulk modifications, e.g. adjusting internal state after a system-wide change.

      Type Parameters:
      T - the expected type of the values
      Parameters:
      modifierFunction - the function to apply to each entry

    • get

      <T> T get(Object id)
      Retrieves the value associated with the given id, or null if not found.
      Type Parameters:
      T - the expected type of the value
      Parameters:
      id - the key to retrieve
      Returns:
      the cached value, or null if absent

    • supplyAll

      default <U,T> void supplyAll(Iterable<? extends U> lookups, Function<? super U, ?> keyFunction, BiConsumer<? super U, ? super T> valueConsumer)
      Supplies every present value from an ordered group of lookups.

      The default implementation preserves the ordinary per-key get(Object) contract. Implementations may override this method to amortize shared bookkeeping or lock transitions, but must retain the same per-key access and eviction semantics in iteration order.

      Type Parameters:
      U - lookup value type
      T - cache value type
      Parameters:
      lookups - lookup values
      keyFunction - derives the cache key for a lookup
      valueConsumer - receives a lookup and its cached value when present

    • getOrDefault

      default <T> T getOrDefault(Object id, T defaultValue)
      Retrieves the value associated with the given id, or returns the specified default if not present.
      Type Parameters:
      T - the expected type of the value
      Parameters:
      id - the key to retrieve
      defaultValue - the value to return if the key is not found
      Returns:
      the cached value or the default

    • containsKey

      boolean containsKey(Object id)
      Checks whether the cache contains an entry for the given id.
      Parameters:
      id - the key to check
      Returns:
      true if the key exists in the cache, false otherwise

    • remove

      <T> T remove(Object id)
      Removes the entry associated with the given id, if present.
      Type Parameters:
      T - the expected type of the removed value
      Parameters:
      id - the key to remove
      Returns:
      the removed value, or null if no value was associated with the key

    • clear

      void clear()
      Removes all entries from the cache.

    • size

      int size()
      Returns the number of entries currently stored in the cache.
      Returns:
      the number of entries

    • isEmpty

      default boolean isEmpty()
      Returns whether the cache is empty.
      Returns:
      true if the cache is empty; otherwise false

    • registerEvictionListener

      Registration registerEvictionListener(Consumer<CacheEviction> listener)
      Registers a listener to be notified whenever a cache entry is evicted or removed.
      Parameters:
      listener - a function that consumes CacheEvictions
      Returns:
      a registration that can be used to cancel the listener

    • rebuild

      Cache rebuild()
      Returns a fresh cache instance with the same configuration and no stored entries.

    • close

      void close()
      Closes the cache and releases all associated resources.