Class ConsistentHash<T>

java.lang.Object
cloud.opencode.base.hash.consistent.ConsistentHash<T>
Type Parameters:
T - node data type | 节点数据类型
All Implemented Interfaces:
NodeLocator<T>
public final class ConsistentHash<T> extends Object implements NodeLocator<T>
Consistent hash ring implementation 一致性哈希环实现

Implements consistent hashing with virtual nodes for improved load distribution. Supports dynamic node addition/removal with minimal key migration.

实现带虚拟节点的一致性哈希以改善负载分布。 支持动态节点添加/删除，最小化键迁移。

Features | 主要功能:

  • Virtual nodes for better distribution - 虚拟节点以获得更好的分布
  • Weight-based virtual node count - 基于权重的虚拟节点数量
  • Optional concurrent access support - 可选的并发访问支持
  • Distribution statistics - 分布统计

Usage Examples | 使用示例:

ConsistentHash<String> ring = ConsistentHash.<String>builder()
    .virtualNodeCount(150)
    .addNode("server1", "192.168.1.1")
    .addNode("server2", "192.168.1.2", 2)
    .concurrent(true)
    .build();

String server = ring.get("user_123");
List<String> replicas = ring.get("data_key", 3);

Security | 安全性:

  • Thread-safe: Optional (use concurrent(true)) - 线程安全: 可选（使用concurrent(true)）

Performance | 性能特性:

  • Time complexity: O(log n) for lookup where n = virtual nodes - 查找 O(log n), n为虚拟节点数
  • Space complexity: O(n * v) where v = virtual replicas - O(n * v), v为虚拟副本数
Since:
JDK 25, opencode-base-hash V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • get

      public T get(Object key)
      Gets the node for a key 获取键对应的节点
      Parameters:
      key - the key | 键
      Returns:
      node data, or null if ring is empty | 节点数据，如果环为空则返回null

    • get

      public List<T> get(Object key, int replicas)
      Gets multiple nodes for a key (for replicas) 获取键对应的多个节点（用于副本）
      Parameters:
      key - the key | 键
      replicas - number of replicas | 副本数
      Returns:
      list of node data (distinct physical nodes) | 节点数据列表（不同的物理节点）

    • locate

      public T locate(long hashValue)
      Description copied from interface: NodeLocator
      Locates the node for a given hash value 为给定的哈希值定位节点
      Specified by:
      locate in interface NodeLocator<T>
      Parameters:
      hashValue - hash value | 哈希值
      Returns:
      the node data, or null if ring is empty | 节点数据，如果环为空则返回null

    • locateAll

      public List<T> locateAll(long hashValue, int count)
      Description copied from interface: NodeLocator
      Locates multiple nodes for replica placement 为副本放置定位多个节点

      Returns nodes in clockwise order from the hash position. Duplicate physical nodes are excluded.

      按哈希位置的顺时针顺序返回节点。排除重复的物理节点。

      Specified by:
      locateAll in interface NodeLocator<T>
      Parameters:
      hashValue - hash value | 哈希值
      count - number of nodes to return | 要返回的节点数
      Returns:
      list of node data | 节点数据列表

    • getVirtualNode

      public VirtualNode<T> getVirtualNode(long hashValue)
      Description copied from interface: NodeLocator
      Gets the virtual node at the specified position 获取指定位置的虚拟节点
      Specified by:
      getVirtualNode in interface NodeLocator<T>
      Parameters:
      hashValue - hash value | 哈希值
      Returns:
      virtual node, or null if ring is empty | 虚拟节点，如果环为空则返回null

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: NodeLocator
      Checks if the ring is empty 检查环是否为空
      Specified by:
      isEmpty in interface NodeLocator<T>
      Returns:
      true if empty | 如果为空返回true

    • getVirtualNodeCount

      public int getVirtualNodeCount()
      Description copied from interface: NodeLocator
      Gets the total number of virtual nodes 获取虚拟节点总数
      Specified by:
      getVirtualNodeCount in interface NodeLocator<T>
      Returns:
      virtual node count | 虚拟节点数量

    • addNode

      public void addNode(String nodeId, T nodeData)
      Adds a node with default weight 添加默认权重的节点
      Parameters:
      nodeId - node id | 节点ID
      nodeData - node data | 节点数据

    • addNode

      public void addNode(String nodeId, T nodeData, int weight)
      Adds a weighted node 添加带权重的节点
      Parameters:
      nodeId - node id | 节点ID
      nodeData - node data | 节点数据
      weight - node weight | 节点权重

    • removeNode

      public void removeNode(String nodeId)
      Removes a node 移除节点
      Parameters:
      nodeId - node id | 节点ID

    • getNodes

      public Set<HashNode<T>> getNodes()
      Gets all physical nodes 获取所有物理节点
      Returns:
      set of nodes | 节点集合

    • getNodeCount

      public int getNodeCount()
      Gets the physical node count 获取物理节点数量
      Returns:
      node count | 节点数量

    • clear

      public void clear()
      Clears all nodes 清空所有节点

    • getDistribution

      public Map<String,Integer> getDistribution(Collection<?> keys)
      Gets key distribution across nodes 获取键在节点间的分布
      Parameters:
      keys - collection of keys | 键集合
      Returns:
      map of node id to key count | 节点ID到键数量的映射

    • getMigrationCount

      public int getMigrationCount(String nodeId, Collection<?> keys)
      Gets the migration count if a node is removed 获取如果移除节点需要迁移的键数量
      Parameters:
      nodeId - node id | 节点ID
      keys - collection of keys | 键集合
      Returns:
      number of keys that would be migrated | 需要迁移的键数量

    • builder

      public static <T> ConsistentHashBuilder<T> builder()
      Creates a builder 创建构建器
      Type Parameters:
      T - node data type | 节点数据类型
      Returns:
      builder | 构建器