Class SoftReferenceCache

java.lang.Object
io.fluxzero.sdk.persisting.caching.SoftReferenceCache
All Implemented Interfaces:
AutoCloseable
public class SoftReferenceCache extends Object implements AutoCloseable
Cache implementation using key-level synchronized access and soft references for value storage.

This cache is optimized for concurrent environments and provides built-in support for:

  • Automatic eviction based on max size (LRU policy)
  • Reference-based eviction when values are no longer strongly reachable (via SoftReference)
  • Expiration after a configurable duration
  • Eviction notification via registered CacheEviction listeners

The cache ensures thread safety through synchronized access on its internal LinkedHashMap and striped locking for computations. Equal keys always use the same stripe, preserving atomic updates without allocating or globally interning a lock value for every cache operation.

Threading: Eviction listeners and expiration polling run on background threads. The valueMap itself is backed by a synchronized LinkedHashMap with LRU eviction behavior.

See Also:
  • Cache
  • CacheEviction

  • Constructor Details

    • SoftReferenceCache

      public SoftReferenceCache()
      Constructs a cache with a default maximum size of 1,000,000 entries and no expiration.

    • SoftReferenceCache

      public SoftReferenceCache(int maxSize)
      Constructs a cache with a specified max size and no expiration.

    • SoftReferenceCache

      public SoftReferenceCache(int maxSize, Duration expiry)
      Constructs a cache with specified size and expiration. Uses a single-threaded executor for eviction notifications.

    • SoftReferenceCache

      public SoftReferenceCache(int maxSize, Executor evictionNotifier, Duration expiry)
      Constructs a cache with specified size, executor for eviction notifications and expiration.

    • SoftReferenceCache

      public SoftReferenceCache(int maxSize, Executor evictionNotifier, Duration expiry, Duration expiryCheckDelay, boolean softReferences)
      Constructs a cache with full configuration of size, eviction executor, expiration delay, and expiration check frequency.

    • SoftReferenceCache

      protected SoftReferenceCache(int maxSize, Executor evictionNotifier, Duration expiry, Duration expiryCheckDelay, boolean softReferences, Clock clock)

  • Method Details

    • compute

      public <T> T compute(Object id, BiFunction<? super Object, ? super T, ? extends T> mappingFunction)
      Returns a synchronized computation that adds, removes, or updates a cache entry. A fixed hash stripe preserves per-key atomicity without allocating and globally interning a mutex String for every cache operation.

    • mergeAll

      public <T> void mergeAll(Map<?, ? extends T> values, BiFunction<? super T, ? super T, ? extends T> mergeFunction)

    • updateAll

      public <T> void updateAll(Map<?, ? extends Function<? super T, ? extends T>> updates)

    • modifyEach

      public <T> void modifyEach(BiFunction<? super Object, ? super T, ? extends T> modifierFunction)

    • put

      public Object put(Object id, Object value)

    • putIfAbsent

      public Object putIfAbsent(Object id, Object value)

    • computeIfAbsent

      public <T> T computeIfAbsent(Object id, Function<? super Object, T> mappingFunction)

    • computeIfPresent

      public <T> T computeIfPresent(Object id, BiFunction<? super Object, ? super T, ? extends T> mappingFunction)

    • remove

      public <T> T remove(Object id)

    • get

      public <T> T get(Object id)

    • containsKey

      public boolean containsKey(Object id)

    • clear

      public void clear()

    • size

      public int size()

    • registerEvictionListener

      public io.fluxzero.common.Registration registerEvictionListener(Consumer<io.fluxzero.common.caching.CacheEviction> listener)

    • rebuild

      public io.fluxzero.common.caching.Cache rebuild()

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • wrap

      protected SoftReferenceCache.CacheReference wrap(Object id, Object value)

    • unwrap

      protected <T> T unwrap(SoftReferenceCache.CacheReference ref)

    • pollReferenceQueue

      protected void pollReferenceQueue()

    • removeExpiredReferences

      protected void removeExpiredReferences()

    • registerEviction

      protected void registerEviction(SoftReferenceCache.CacheReference reference, io.fluxzero.common.caching.CacheEviction.Reason reason)

    • updateAll

      default <U,T> void updateAll(Iterable<? extends U> arg0, Function<? super U, ?> arg1, BiFunction<? super U, ? super T, ? extends T> arg2)

    • updateAll

      default <U,T> void updateAll(Iterable<? extends U> arg0, Function<? super U, ?> arg1, Function<? super U, ?> arg2, BiFunction<? super U, ? super T, ? extends T> arg3)

    • supplyAll

      default <U,T> void supplyAll(Iterable<? extends U> arg0, Function<? super U, ?> arg1, BiConsumer<? super U, ? super T> arg2)

    • getOrDefault

      default <T> T getOrDefault(Object arg0, T arg1)

    • isEmpty

      default boolean isEmpty()