Package io.github.dhruv1110.jcachex.distributed

Interface DistributedCache<K,​V>

  • Type Parameters:
    K - the type of keys maintained by this cache
    V - the type of mapped values
    All Known Implementing Classes:
    AbstractDistributedCache, KubernetesDistributedCache
    public interface DistributedCache<K,​V>
    Distributed cache interface that extends the base Cache interface with multi-node capabilities.

    This interface provides seamless scaling from local to distributed caching while maintaining the familiar Cache API. It supports various consistency models, replication strategies, and automatic failover mechanisms.

    Key Features:

    • Seamless Scaling: Start local, scale to distributed without API changes
    • Multiple Consistency Models: Strong, eventual, and session consistency
    • Automatic Replication: Data replicated across nodes for high availability
    • Partition Tolerance: Continues operating during network partitions
    • Self-Healing: Automatic node discovery and failure recovery
    • Hybrid Performance: Local performance with distributed availability

    Usage Examples:

    
 // Basic distributed cache
 DistributedCache<String, User> cache = DistributedCache.<String, User>builder()
         .clusterName("user-service")
         .nodes("cache-node-1:8080", "cache-node-2:8080", "cache-node-3:8080")
         .replicationFactor(2)
         .consistencyLevel(ConsistencyLevel.EVENTUAL)
         .build();

 // Use exactly like a local cache
 cache.put("user123", user);
 User retrievedUser = cache.get("user123"); // May come from any node

 // Distributed-specific operations
 cache.invalidateGlobally("user123"); // Invalidate across all nodes
 ClusterTopology topology = cache.getClusterTopology();
 Map<String, CacheStats> nodeStats = cache.getPerNodeStats();

    Consistency Models:

    • STRONG: All nodes see the same data immediately (CP model)
    • EVENTUAL: Nodes eventually converge to the same state (AP model)
    • SESSION: Guarantees consistency within a session/thread
    • MONOTONIC_READ: Once a value is read, subsequent reads return same or newer
    Since:
    1.0.0

    • Method Detail

      • putAsync

        CompletableFuture<Void> putAsync​(K key,
                                 V value)
        Puts a value in the cache with the specified consistency level.
        Parameters:
        key - the key
        value - the value
        Returns:
        CompletableFuture that completes when the operation is done

      • getAsync

        CompletableFuture<V> getAsync​(K key)
        Gets a value from the cache with the specified consistency level.
        Parameters:
        key - the key
        Returns:
        CompletableFuture containing the value or null if not found

      • put

        void put​(K key,
         V value)

      • get

        V get​(K key)

      • invalidateGlobally

        CompletableFuture<Void> invalidateGlobally​(K key)
        Invalidates a key across all nodes in the cluster.
        Parameters:
        key - the key to invalidate
        Returns:
        CompletableFuture that completes when invalidation is propagated

      • invalidateGlobally

        CompletableFuture<Void> invalidateGlobally​(Collection<K> keys)
        Invalidates multiple keys across all nodes in the cluster.
        Parameters:
        keys - the keys to invalidate
        Returns:
        CompletableFuture that completes when invalidation is propagated

      • clearGlobally

        CompletableFuture<Void> clearGlobally()
        Clears all entries across all nodes in the cluster.
        Returns:
        CompletableFuture that completes when clear is propagated

      • getPerNodeStats

        Map<String,​CacheStats> getPerNodeStats()
        Returns cache statistics for each node in the cluster.
        Returns:
        map of node ID to cache statistics

      • getReplicationFactor

        int getReplicationFactor()
        Returns the replication factor for this cache.
        Returns:
        number of replicas maintained for each entry

      • rebalance

        CompletableFuture<Void> rebalance()
        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.

        Returns:
        CompletableFuture that completes when rebalancing is done