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 per-key locking using intern() on a string prefix plus key combination. While this does introduce some memory overhead due to string interning, it ensures atomic updates for concurrent access to the same key.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static interface	SoftReferenceCache.CacheReference
class	SoftReferenceCache.HardCacheReference
protected class	SoftReferenceCache.SoftCacheReference

Field Summary

Fields

Modifier and Type	Field	Description
protected static final String	mutexPrecursor

Constructor Summary

Constructors

Modifier	Constructor	Description
	SoftReferenceCache()	Constructs a cache with a default maximum size of 1,000,000 entries and no expiration.
	SoftReferenceCache(int maxSize)	Constructs a cache with a specified max size and no expiration.
	SoftReferenceCache(int maxSize, Duration expiry)	Constructs a cache with specified size and expiration.
	SoftReferenceCache(int maxSize, Executor evictionNotifier, Duration expiry)	Constructs a cache with specified size, executor for eviction notifications and expiration.
	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.
protected	SoftReferenceCache(int maxSize, Executor evictionNotifier, Duration expiry, Duration expiryCheckDelay, boolean softReferences, Clock clock)

Method Summary

Modifier and Type	Method	Description
void	clear()
void	close()
<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.
<T> T	computeIfAbsent(Object id, Function<? super Object, T> mappingFunction)
<T> T	computeIfPresent(Object id, BiFunction<? super Object, ? super T, ? extends T> mappingFunction)
boolean	containsKey(Object id)
<T> T	get(Object id)
default <T> T	getOrDefault(Object arg0, T arg1)
default boolean	isEmpty()
<T> void	modifyEach(BiFunction<? super Object, ? super T, ? extends T> modifierFunction)
protected void	pollReferenceQueue()
Object	put(Object id, Object value)
Object	putIfAbsent(Object id, Object value)
io.fluxzero.common.caching.Cache	rebuild()
protected void	registerEviction(SoftReferenceCache.CacheReference reference, io.fluxzero.common.caching.CacheEviction.Reason reason)
io.fluxzero.common.Registration	registerEvictionListener(Consumer<io.fluxzero.common.caching.CacheEviction> listener)
<T> T	remove(Object id)
protected void	removeExpiredReferences()
int	size()
protected <T> T	unwrap(SoftReferenceCache.CacheReference ref)
protected SoftReferenceCache.CacheReference	wrap(Object id, Object value)

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

mutexPrecursor

protected static final String mutexPrecursor

See Also:

• Constant Field Values

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. Internally uses per-key String.intern() synchronization to prevent race conditions.

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)

getOrDefault

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

isEmpty

default boolean isEmpty()