Class AdaptiveObjectCache

java.lang.Object
io.fluxzero.common.caching.AdaptiveObjectCache
All Implemented Interfaces:
Cache
public class AdaptiveObjectCache extends Object implements Cache
Cache implementation backed by the common hard-reference memory-aware cache support.

The default constructors are intentionally count-bounded: every cached value counts as one entry, regardless of the size of its object graph. Use the weighted constructor only for values with a reliable size estimate, such as serialized payloads.

  • Field Details

  • Constructor Details

    • AdaptiveObjectCache

      public AdaptiveObjectCache()

    • AdaptiveObjectCache

      public AdaptiveObjectCache(int maxSize)

    • AdaptiveObjectCache

      public AdaptiveObjectCache(int maxSize, Duration expiry)
      Constructs a count-bounded cache with a maximum entry age.

    • AdaptiveObjectCache

      public AdaptiveObjectCache(int maxSize, MemoryPressureController memoryPressureController)

    • AdaptiveObjectCache

      public AdaptiveObjectCache(int maxSize, MemoryPressureController memoryPressureController, Duration expiry)
      Constructs a count-bounded cache with memory-pressure trimming and a maximum entry age.

    • AdaptiveObjectCache

      public AdaptiveObjectCache(long maxWeight, long maxEntryWeight, ToLongBiFunction<? super Object, ? super Object> weigher, MemoryPressureController memoryPressureController)

    • AdaptiveObjectCache

      public AdaptiveObjectCache(long maxWeight, long maxEntryWeight, ToLongBiFunction<? super Object, ? super Object> weigher, MemoryPressureController memoryPressureController, Duration expiry)
      Constructs a weighted cache with memory-pressure trimming and a maximum entry age.

    • AdaptiveObjectCache

      public AdaptiveObjectCache(int maxSize, MemoryPressureController memoryPressureController, Duration expiry, Clock clock)

    • AdaptiveObjectCache

      public AdaptiveObjectCache(long maxWeight, long maxEntryWeight, ToLongBiFunction<? super Object, ? super Object> weigher, MemoryPressureController memoryPressureController, Duration expiry, Clock clock)

  • Method Details

    • put

      public Object put(Object id, Object value)
      Description copied from interface: Cache
      Puts a value in the cache for the given id, overwriting any existing value.
      Specified by:
      put in interface Cache
      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

      public Object putIfAbsent(Object id, Object value)
      Description copied from interface: Cache
      Associates the specified value with the given id only if no value is currently associated.
      Specified by:
      putIfAbsent in interface Cache
      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

      public <T> T computeIfAbsent(Object id, Function<? super Object, T> mappingFunction)
      Description copied from interface: Cache
      If a value is not already associated with the given id, computes and stores one using the given function.
      Specified by:
      computeIfAbsent in interface Cache
      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

      public <T> T computeIfPresent(Object id, BiFunction<? super Object, ? super T, ? extends T> mappingFunction)
      Description copied from interface: Cache
      If a value is already associated with the given id, computes a new value using the provided function and replaces the old one.
      Specified by:
      computeIfPresent in interface 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 from the current one
      Returns:
      the newly computed value, or null if the mapping function returned null

    • compute

      public <T> T compute(Object id, BiFunction<? super Object, ? super T, ? extends T> mappingFunction)
      Description copied from interface: Cache
      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.

      Specified by:
      compute in interface 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

      public <T> void mergeAll(Map<?, ? extends T> values, BiFunction<? super T, ? super T, ? extends T> mergeFunction)
      Description copied from interface: Cache
      Merges a bounded group of candidate values into this cache.

      The default implementation preserves the ordinary per-key Cache.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.

      Specified by:
      mergeAll in interface Cache
      Type Parameters:
      T - value type
      Parameters:
      values - candidate value by cache key
      mergeFunction - selects the retained value from the current and candidate value

    • updateAll

      public <T> void updateAll(Map<?, ? extends Function<? super T, ? extends T>> updates)
      Description copied from interface: Cache
      Applies independent per-key update functions as one bounded cache operation.

      The default implementation preserves the ordinary per-key Cache.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.

      Specified by:
      updateAll in interface Cache
      Type Parameters:
      T - value type
      Parameters:
      updates - update function by cache key

    • updateAll

      public <U,T> void updateAll(Iterable<? extends U> updates, Function<? super U, ?> keyFunction, BiFunction<? super U, ? super T, ? extends T> updateFunction)
      Description copied from interface: Cache
      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 Cache.compute(Object, BiFunction) contract; implementations may override it to amortize locking and pressure bookkeeping.

      Specified by:
      updateAll in interface Cache
      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

      public <U,T> void updateAll(Iterable<? extends U> updates, Function<? super U, ?> lookupKeyFunction, Function<? super U, ?> retainedKeyFunction, BiFunction<? super U, ? super T, ? extends T> updateFunction)
      Description copied from interface: Cache
      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.

      Specified by:
      updateAll in interface Cache
      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

      public <T> void modifyEach(BiFunction<? super Object, ? super T, ? extends T> modifierFunction)
      Description copied from interface: Cache
      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.

      Specified by:
      modifyEach in interface Cache
      Type Parameters:
      T - the expected type of the values
      Parameters:
      modifierFunction - the function to apply to each entry

    • get

      public <T> T get(Object id)
      Description copied from interface: Cache
      Retrieves the value associated with the given id, or null if not found.
      Specified by:
      get in interface Cache
      Type Parameters:
      T - the expected type of the value
      Parameters:
      id - the key to retrieve
      Returns:
      the cached value, or null if absent

    • supplyAll

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

      The default implementation preserves the ordinary per-key Cache.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.

      Specified by:
      supplyAll in interface Cache
      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

    • containsKey

      public boolean containsKey(Object id)
      Description copied from interface: Cache
      Checks whether the cache contains an entry for the given id.
      Specified by:
      containsKey in interface Cache
      Parameters:
      id - the key to check
      Returns:
      true if the key exists in the cache, false otherwise

    • remove

      public <T> T remove(Object id)
      Description copied from interface: Cache
      Removes the entry associated with the given id, if present.
      Specified by:
      remove in interface Cache
      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

      public void clear()
      Description copied from interface: Cache
      Removes all entries from the cache.
      Specified by:
      clear in interface Cache

    • size

      public int size()
      Description copied from interface: Cache
      Returns the number of entries currently stored in the cache.
      Specified by:
      size in interface Cache
      Returns:
      the number of entries

    • registerEvictionListener

      public Registration registerEvictionListener(Consumer<CacheEviction> listener)
      Description copied from interface: Cache
      Registers a listener to be notified whenever a cache entry is evicted or removed.
      Specified by:
      registerEvictionListener in interface Cache
      Parameters:
      listener - a function that consumes CacheEvictions
      Returns:
      a registration that can be used to cancel the listener

    • rebuild

      public Cache rebuild()
      Description copied from interface: Cache
      Returns a fresh cache instance with the same configuration and no stored entries.
      Specified by:
      rebuild in interface Cache

    • close

      public void close()
      Description copied from interface: Cache
      Closes the cache and releases all associated resources.
      Specified by:
      close in interface Cache

    • weight

      public long weight()

    • trimForMemoryPressure

      public boolean trimForMemoryPressure()