Package io.github.dhruv1110.jcachex.distributed.impl

Class AbstractDistributedCache<K,V>

java.lang.Object

io.github.dhruv1110.jcachex.distributed.impl.AbstractDistributedCache<K,V>

Type Parameters:

K - the type of keys

V - the type of values

All Implemented Interfaces:

DistributedCache<K,V>

Direct Known Subclasses:

KubernetesDistributedCache

public abstract class AbstractDistributedCache<K,V>
extends Object
implements DistributedCache<K,V>

Abstract base class for distributed cache implementations.

This class provides common functionality for all distributed cache types including: consistent hashing with virtual nodes, memory management, metrics tracking, and pluggable communication protocols.

Common Features:

• Consistent Hashing: Virtual nodes for even data distribution
• Memory Management: Per-node memory limits with eviction
• Metrics: Comprehensive metrics collection
• Communication: Pluggable communication protocols
• Node Management: Dynamic cluster topology management

Since:

1.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	AbstractDistributedCache.Builder<K,V>
protected static class	AbstractDistributedCache.ConsistentHashRing
protected static class	AbstractDistributedCache.NodeUpdateResult	Result of node update operations in the consistent hash ring.

Nested classes/interfaces inherited from interface io.github.dhruv1110.jcachex.distributed.DistributedCache

DistributedCache.ClusterTopology, DistributedCache.DistributedMetrics, DistributedCache.NodeInfo, DistributedCache.NodeStatus

Field Summary

Fields

Modifier and Type	Field	Description
protected String	clusterName
protected Map<String,DistributedCache.NodeInfo>	clusterNodes
protected CommunicationProtocol<K,V>	communicationProtocol
protected AtomicLong	conflictResolutions
protected AtomicLong	currentMemoryBytes
protected String	currentNodeId
protected ScheduledExecutorService	discoveryScheduler
protected ExecutorService	distributionExecutor
protected AbstractDistributedCache.ConsistentHashRing	hashRing
protected Set<String>	healthyNodes
protected AtomicBoolean	isRunning
protected Cache<K,V>	localCache
protected long	maxMemoryBytes
protected AtomicLong	networkFailures
protected AtomicLong	networkRequests
protected Duration	networkTimeout
protected NodeDiscovery	nodeDiscovery
protected int	partitionCount
protected Map<String,AtomicLong>	perNodeLatencies
protected boolean	readRepairEnabled
protected AtomicLong	replicationLag
protected AtomicLong	topologyVersion

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractDistributedCache(AbstractDistributedCache.Builder<K,V> builder)

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Void>	clearGlobally()	Clears all entries across all nodes in the cluster.
protected long	estimateSize(K key, V value)
protected void	evictToFreeMemory(long bytesToFree)
protected String	generateNodeId()	Generate a unique node ID for this cache instance.
V	get(K key)
CompletableFuture<V>	getAsync(K key)	Gets a value from the cache with the specified consistency level.
protected V	getFromRemoteNode(String nodeAddress, K key)
protected abstract void	initializeCluster()	Initialize cluster-specific functionality.
CompletableFuture<Void>	invalidateGlobally(Collection<K> keys)	Invalidates multiple keys across all nodes in the cluster.
CompletableFuture<Void>	invalidateGlobally(K key)	Invalidates a key across all nodes in the cluster.
void	put(K key, V value)
CompletableFuture<Void>	putAsync(K key, V value)	Puts a value in the cache with the specified consistency level.
protected void	putToRemoteNode(String nodeAddress, K key, V value)
CompletableFuture<Void>	rebalance()	Forces a manual rebalancing of the cache across nodes.
CompletableFuture<Void>	rebalance(Set<String> healthyNodes)
protected void	recordMemoryRemoval(long bytes)
protected void	recordMemoryUsage(long bytes)
V	remove(K key)
protected V	removeFromRemoteNode(String nodeAddress, K key)

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.github.dhruv1110.jcachex.distributed.DistributedCache

getClusterTopology, getDistributedMetrics, getNodeStatuses, getPerNodeStats, getReplicationFactor

Field Detail

clusterName

protected final String clusterName

partitionCount

protected final int partitionCount

networkTimeout

protected final Duration networkTimeout

maxMemoryBytes

protected final long maxMemoryBytes

readRepairEnabled

protected final boolean readRepairEnabled

currentNodeId

protected final String currentNodeId

localCache

protected final Cache<K,V> localCache

hashRing

protected final AbstractDistributedCache.ConsistentHashRing hashRing

communicationProtocol

protected final CommunicationProtocol<K,V> communicationProtocol

nodeDiscovery

protected final NodeDiscovery nodeDiscovery

distributionExecutor

protected final ExecutorService distributionExecutor

discoveryScheduler

protected final ScheduledExecutorService discoveryScheduler

isRunning

protected final AtomicBoolean isRunning

healthyNodes

protected final Set<String> healthyNodes

clusterNodes

protected final Map<String,DistributedCache.NodeInfo> clusterNodes

topologyVersion

protected final AtomicLong topologyVersion

currentMemoryBytes

protected final AtomicLong currentMemoryBytes

networkRequests

protected final AtomicLong networkRequests

networkFailures

protected final AtomicLong networkFailures

replicationLag

protected final AtomicLong replicationLag

conflictResolutions

protected final AtomicLong conflictResolutions

perNodeLatencies

protected final Map<String,AtomicLong> perNodeLatencies

Constructor Detail

AbstractDistributedCache

protected AbstractDistributedCache(AbstractDistributedCache.Builder<K,V> builder)

Method Detail

generateNodeId

protected String generateNodeId()

Generate a unique node ID for this cache instance. Subclasses can override this for platform-specific node identification.

initializeCluster

protected abstract void initializeCluster()

Initialize cluster-specific functionality. Subclasses should implement this for their specific discovery mechanism.

recordMemoryUsage

protected void recordMemoryUsage(long bytes)

recordMemoryRemoval

protected void recordMemoryRemoval(long bytes)

evictToFreeMemory

protected void evictToFreeMemory(long bytesToFree)

estimateSize

protected long estimateSize(K key,
                            V value)

getAsync

public CompletableFuture<V> getAsync(K key)

Description copied from interface: DistributedCache

Gets a value from the cache with the specified consistency level.

Specified by:

getAsync in interface DistributedCache<K,V>

Parameters:

key - the key

Returns:

CompletableFuture containing the value or null if not found

putAsync

public CompletableFuture<Void> putAsync(K key,
                                        V value)

Description copied from interface: DistributedCache

Puts a value in the cache with the specified consistency level.

Specified by:

putAsync in interface DistributedCache<K,V>

Parameters:

key - the key

value - the value

Returns:

CompletableFuture that completes when the operation is done

get

public V get(K key)

Specified by:

get in interface DistributedCache<K,V>

invalidateGlobally

public CompletableFuture<Void> invalidateGlobally(Collection<K> keys)

Description copied from interface: DistributedCache

Invalidates multiple keys across all nodes in the cluster.

Specified by:

invalidateGlobally in interface DistributedCache<K,V>

Parameters:

keys - the keys to invalidate

Returns:

CompletableFuture that completes when invalidation is propagated

rebalance

public CompletableFuture<Void> rebalance()

Description copied from interface: DistributedCache

Forces a manual rebalancing of the cache across nodes.

This is typically done automatically, but can be triggered manually after adding or removing nodes from the cluster.

Specified by:

rebalance in interface DistributedCache<K,V>

Returns:

CompletableFuture that completes when rebalancing is done

rebalance

public CompletableFuture<Void> rebalance(Set<String> healthyNodes)

invalidateGlobally

public CompletableFuture<Void> invalidateGlobally(K key)

Description copied from interface: DistributedCache

Invalidates a key across all nodes in the cluster.

Specified by:

invalidateGlobally in interface DistributedCache<K,V>

Parameters:

key - the key to invalidate

Returns:

CompletableFuture that completes when invalidation is propagated

clearGlobally

public CompletableFuture<Void> clearGlobally()

Description copied from interface: DistributedCache

Clears all entries across all nodes in the cluster.

Specified by:

clearGlobally in interface DistributedCache<K,V>

Returns:

CompletableFuture that completes when clear is propagated

put

public void put(K key,
                V value)

Specified by:

put in interface DistributedCache<K,V>

remove

public V remove(K key)

getFromRemoteNode

protected V getFromRemoteNode(String nodeAddress,
                              K key)

putToRemoteNode

protected void putToRemoteNode(String nodeAddress,
                               K key,
                               V value)
                        throws Exception

Throws:

Exception

removeFromRemoteNode

protected V removeFromRemoteNode(String nodeAddress,
                                 K key)