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 Superinterfaces:
    Cache<K,​V>
    All Known Implementing Classes:
    DefaultDistributedCache
    public interface DistributedCache<K,​V>
extends Cache<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

      • putWithConsistency

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

      • getWithConsistency

        CompletableFuture<V> getWithConsistency​(K key,
                                        DistributedCache.ConsistencyLevel consistencyLevel)
        Gets a value from the cache with the specified consistency level.
        Parameters:
        key - the key
        consistencyLevel - the consistency level for this operation
        Returns:
        CompletableFuture containing the value or null if not found

      • 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

      • getConsistencyLevel

        DistributedCache.ConsistencyLevel getConsistencyLevel()
        Returns the consistency level used by this cache.
        Returns:
        the default consistency level

      • 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

      • addNode

        CompletableFuture<Void> addNode​(String nodeAddress)
        Adds a new node to the cluster.
        Parameters:
        nodeAddress - the address of the new node
        Returns:
        CompletableFuture that completes when the node is added

      • removeNode

        CompletableFuture<Void> removeNode​(String nodeId)
        Removes a node from the cluster.
        Parameters:
        nodeId - the ID of the node to remove
        Returns:
        CompletableFuture that completes when the node is removed

      • setReadRepairEnabled

        void setReadRepairEnabled​(boolean enabled)
        Enables or disables read repair for this cache.

        Read repair detects and fixes inconsistencies during read operations.

        Parameters:
        enabled - whether to enable read repair

      • isReadRepairEnabled

        boolean isReadRepairEnabled()
        Returns whether read repair is enabled.
        Returns:
        true if read repair is enabled

      • builder

        static <K,​V> DistributedCache.Builder<K,​V> builder()
        Creates a new distributed cache builder.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        new builder instance