Class IdempotencyManager

java.lang.Object

com.loomcache.server.handler.IdempotencyManager

All Implemented Interfaces:

AutoCloseable

public class IdempotencyManager
extends Object
implements AutoCloseable

Manages server-side request deduplication for idempotent operations.

Tracks completed requests by client ID + request ID and returns cached responses for retried requests. Uses LRU eviction when cache is full and a background cleanup thread for expired entries.

Thread-safe: uses ReentrantLock for coordinated operations and ConcurrentHashMap for the underlying cache.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	IdempotencyManager.CachedResponse	Record representing a cached response with metadata.
static final record	IdempotencyManager.IdempotencyKey	Record representing an idempotency key (client ID + request ID).
static final record	IdempotencyManager.IdempotencyStats	Statistics for idempotency tracking.

Constructor Summary

Constructors

Constructor	Description
IdempotencyManager()	Creates a new IdempotencyManager with default TTL (60s) and cache size (100,000).
IdempotencyManager(long ttlMillis, int maxCacheSize)	Creates a new IdempotencyManager with custom TTL and max cache size.
IdempotencyManager(long ttlMillis, int maxCacheSize, @Nullable io.micrometer.core.instrument.MeterRegistry meterRegistry)

Method Summary

Modifier and Type	Method	Description
void	clear()	Clears all cached entries.
void	clearExpired()	Clears expired entries from the cache.
void	close()
Message	deduplicate(IdempotencyManager.IdempotencyKey key, Supplier<Message> supplier)	Deduplicates a request.
Message	deduplicate(IdempotencyManager.IdempotencyKey key, Supplier<Message> supplier, Predicate<Exception> retainPendingOnException)
Message	deduplicate(IdempotencyManager.IdempotencyKey key, Supplier<Message> supplier, Predicate<Exception> retainPendingOnException, boolean cpOperation)
IdempotencyManager.IdempotencyStats	getStats()	Returns current statistics about the idempotency manager.
@Nullable Message	peekCompleted(IdempotencyManager.IdempotencyKey key)	Returns a copy of the live cached response for the key, or null if no completed response is currently available.
void	recordCompleted(IdempotencyManager.IdempotencyKey key, Message response)	Record a completed idempotent response without executing the supplier again.
void	recordCompleted(IdempotencyManager.IdempotencyKey key, Message response, boolean cpOperation)
void	restoreCpSnapshotEntries(@Nullable Object rawSnapshotEntries)
void	restoreSnapshotEntries(@Nullable Object rawSnapshotEntries)
ArrayList<HashMap<String,Object>>	snapshotAllEntries(Duration ttl)
ArrayList<HashMap<String,Object>>	snapshotCpEntries(long maxWindowMs)

Methods inherited from class Object

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

Constructor Details

IdempotencyManager

public IdempotencyManager()

Creates a new IdempotencyManager with default TTL (60s) and cache size (100,000).

IdempotencyManager

public IdempotencyManager(long ttlMillis,
 int maxCacheSize)

Creates a new IdempotencyManager with custom TTL and max cache size.

Parameters:

ttlMillis - TTL for cached responses in milliseconds (must be positive)

maxCacheSize - maximum number of entries in the cache (must be positive)

Throws:

InvalidConfigurationException - if ttlMillis or maxCacheSize is zero or negative

IdempotencyManager

public IdempotencyManager(long ttlMillis,
 int maxCacheSize,
 @Nullable io.micrometer.core.instrument.MeterRegistry meterRegistry)

Method Details

deduplicate

public Message deduplicate(IdempotencyManager.IdempotencyKey key,
 Supplier<Message> supplier)

Deduplicates a request. If a cached response exists and hasn't expired, returns it. Otherwise, executes the supplier, caches the result, and returns it.

Parameters:

key - the idempotency key (client ID + request ID)

supplier - the operation to execute if not cached

Returns:

the cached or newly computed response message

deduplicate

public Message deduplicate(IdempotencyManager.IdempotencyKey key,
 Supplier<Message> supplier,
 Predicate<Exception> retainPendingOnException)

deduplicate

public Message deduplicate(IdempotencyManager.IdempotencyKey key,
 Supplier<Message> supplier,
 Predicate<Exception> retainPendingOnException,
 boolean cpOperation)

recordCompleted

public void recordCompleted(IdempotencyManager.IdempotencyKey key,
 Message response)

Record a completed idempotent response without executing the supplier again. Used when a committed result is learned through Raft state-machine apply on followers, so a later leader failover can still deduplicate the retried request.

recordCompleted

public void recordCompleted(IdempotencyManager.IdempotencyKey key,
 Message response,
 boolean cpOperation)

peekCompleted

public @Nullable Message peekCompleted(IdempotencyManager.IdempotencyKey key)

Returns a copy of the live cached response for the key, or null if no completed response is currently available.

getStats

public IdempotencyManager.IdempotencyStats getStats()

Returns current statistics about the idempotency manager.

snapshotCpEntries

public ArrayList<HashMap<String,Object>> snapshotCpEntries(long maxWindowMs)

snapshotAllEntries

public ArrayList<HashMap<String,Object>> snapshotAllEntries(Duration ttl)

restoreSnapshotEntries

public void restoreSnapshotEntries(@Nullable Object rawSnapshotEntries)

restoreCpSnapshotEntries

public void restoreCpSnapshotEntries(@Nullable Object rawSnapshotEntries)

clear

public void clear()

Clears all cached entries.

clearExpired

public void clearExpired()

Clears expired entries from the cache.

close

public void close()

Specified by:

close in interface AutoCloseable