org.apache.ignite.internal.util

## Class GridConsistentHash<N>

- java.lang.Object
- - org.apache.ignite.internal.util.GridConsistentHash<N>

    public class GridConsistentHash<N>
    extends Object

Controls key to node affinity using consistent hash algorithm. This class is thread-safe and does not have to be externally synchronized.

For a good explanation of what consistent hashing is, you can refer to Tom White's Blog.

### Constructor Summary

Constructors
Constructor and Description
`GridConsistentHash()` Constructs consistent hash using default parameters.
`GridConsistentHash(Comparator<N> nodesComp, Object affSeed)` Constructs consistent hash using given affinity seed and hasher function.
`GridConsistentHash(Object affSeed)` Constructs consistent hash using given affinity seed and `MD5` hasher function.

### Method Summary

All Methods Instance Methods Concrete Methods
`boolean` `addNode(N node, int replicas)` Adds a node to consistent hash algorithm.
`void` `addNodes(Collection<N> nodes, int replicas)` Adds nodes to consistent hash algorithm (if nodes are `null` or empty, then no-op).
`boolean` `belongs(Object key, Collection<N> nodes)` Checks if given key belongs to any of the given nodes.
`boolean` `belongs(Object key, int cnt, Collection<N> nodes)` Checks if node the key is mapped to or the given count of its adjacent nodes are contained in given set of nodes.
`boolean` `belongs(Object key, int cnt, N node)` Checks if node the key is mapped to or the given count of its adjacent nodes contain the node passed in.
`boolean` `belongs(Object key, N node)` Checks if key belongs to the given node.
`void` `clear()` Clears all nodes from consistent hash.
`int` `count()` Gets number of distinct nodes, excluding replicas, in consistent hash.
`protected int` `hash(Object o)` Gets hash code for a given object.
`boolean` `isEmpty()` Checks if consistent hash has nodes added to it.
`N` `node(Object key)` Gets node for a key.
`N` `node(Object key, Collection<N> inc)` Gets node for a given key.
`N` `node(Object key, Collection<N> inc, Collection<N> exc)` Gets node for a given key.
`N` `node(Object key, IgnitePredicate<N>... p)` Gets node for a given key.
`Set<N>` `nodes()` Gets set of all distinct nodes in the consistent hash (in no particular order).
`List<N>` `nodes(Object key, int cnt)` Gets specified count of adjacent nodes for a given key.
`List<N>` `nodes(Object key, int cnt, Collection<N> inc)` Gets specified count of adjacent nodes for a given key.
`List<N>` `nodes(Object key, int cnt, Collection<N> inc, Collection<N> exc)` Gets specified count of adjacent nodes for a given key.
`List<N>` `nodes(Object key, int cnt, IgnitePredicate<N>... p)` Gets specified count of adjacent nodes for a given key.
`N` `random()` Picks a random node from consistent hash.
`boolean` `removeNode(N node)` Removes a node and all of its replicas.
`void` `removeNodes(Collection<N> nodes)` Removes given nodes and all their replicas from consistent hash algorithm (if nodes are `null` or empty, then no-op).
`int` `size()` Gets size of all nodes (including replicas) in consistent hash.
`String` `toString()`

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### GridConsistentHash

    public GridConsistentHash(@Nullable
                              Object affSeed)

Constructs consistent hash using given affinity seed and `MD5` hasher function.

Parameters:
  `affSeed` - Affinity seed (will be used as key prefix for hashing).

#### GridConsistentHash

    public GridConsistentHash()

Constructs consistent hash using default parameters.

#### GridConsistentHash

    public GridConsistentHash(@Nullable
                              Comparator<N> nodesComp,
                              @Nullable
                              Object affSeed)

Constructs consistent hash using given affinity seed and hasher function.

Parameters:
  `nodesComp` - Nodes comparator to resolve hash codes collisions.
  `affSeed` - Affinity seed (will be used as key prefix for hashing).

### Method Detail

#### addNodes

    public void addNodes(@Nullable
                         Collection<N> nodes,
                         int replicas)

Adds nodes to consistent hash algorithm (if nodes are `null` or empty, then no-op).

Parameters:
  `nodes` - Nodes to add.
  `replicas` - Number of replicas for every node.

#### addNode

    public boolean addNode(@Nullable
                           N node,
                           int replicas)

Adds a node to consistent hash algorithm.

Parameters:
  `node` - New node (if `null` then no-op).
  `replicas` - Number of replicas for the node.
Returns:
  `True` if node was added, `false` if it is `null` or is already contained in the hash.

#### removeNodes

    public void removeNodes(@Nullable
                            Collection<N> nodes)

Removes given nodes and all their replicas from consistent hash algorithm (if nodes are `null` or empty, then no-op).

Parameters:
  `nodes` - Nodes to remove.

#### removeNode

    public boolean removeNode(@Nullable
                              N node)

Removes a node and all of its replicas.

Parameters:
  `node` - Node to remove (if `null`, then no-op).
Returns:
  `True` if node was removed, `false` if node is `null` or not present in hash.

#### clear

    public void clear()

Clears all nodes from consistent hash.

#### count

    public int count()

Gets number of distinct nodes, excluding replicas, in consistent hash.

Returns:
  Number of distinct nodes, excluding replicas, in consistent hash.

#### size

    public int size()

Gets size of all nodes (including replicas) in consistent hash.

Returns:
  Size of all nodes (including replicas) in consistent hash.

#### isEmpty

    public boolean isEmpty()

Checks if consistent hash has nodes added to it.

Returns:
  `True` if consistent hash is empty, `false` otherwise.

#### nodes

    public Set<N> nodes()

Gets set of all distinct nodes in the consistent hash (in no particular order).

Returns:
  Set of all distinct nodes in the consistent hash.

#### random

    @Nullable
    public N random()

Picks a random node from consistent hash.

Returns:
  Random node from consistent hash or `null` if there are no nodes.

#### node

    @Nullable
    public N node(@Nullable
                            Object key)

Gets node for a key.

Parameters:
  `key` - Key.
Returns:
  Node.

#### node

    @Nullable
    public N node(@Nullable
                            Object key,
                            @Nullable
                            Collection<N> inc)

Gets node for a given key.

Parameters:
  `key` - Key to get node for.
  `inc` - Optional inclusion set. Only nodes contained in this set may be returned. If `null`, then all nodes may be included.
Returns:
  Node for key, or `null` if node was not found.

#### node

    @Nullable
    public N node(@Nullable
                            Object key,
                            @Nullable
                            Collection<N> inc,
                            @Nullable
                            Collection<N> exc)

Gets node for a given key.

Parameters:
  `key` - Key to get node for.
  `inc` - Optional inclusion set. Only nodes contained in this set may be returned. If `null`, then all nodes may be included.
  `exc` - Optional exclusion set. Only nodes not contained in this set may be returned. If `null`, then all nodes may be returned.
Returns:
  Node for key, or `null` if node was not found.

#### node

    @Nullable
    public N node(@Nullable
                            Object key,
                            @Nullable
                            IgnitePredicate<N>... p)

Gets node for a given key.

Parameters:
  `key` - Key to get node for.
  `p` - Optional predicate for node filtering.
Returns:
  Node for key, or `null` if node was not found.

#### nodes

    public List<N> nodes(@Nullable
                         Object key,
                         int cnt)

Gets specified count of adjacent nodes for a given key. If number of nodes in consistent hash is less than specified count, then all nodes are returned.

Parameters:
  `key` - Key to get adjacent nodes for.
  `cnt` - Number of adjacent nodes to get.
Returns:
  List containing adjacent nodes for given key.

#### nodes

    public List<N> nodes(@Nullable
                         Object key,
                         int cnt,
                         @Nullable
                         Collection<N> inc)

Gets specified count of adjacent nodes for a given key. If number of nodes in consistent hash is less than specified count, then all nodes are returned.

Parameters:
  `key` - Key to get adjacent nodes for.
  `cnt` - Number of adjacent nodes to get.
  `inc` - Optional inclusion set. Only nodes contained in this set may be returned. If `null`, then all nodes may be returned.
Returns:
  List containing adjacent nodes for given key.

#### nodes

    public List<N> nodes(@Nullable
                         Object key,
                         int cnt,
                         @Nullable
                         Collection<N> inc,
                         @Nullable
                         Collection<N> exc)

Gets specified count of adjacent nodes for a given key. If number of nodes in consistent hash is less than specified count, then all nodes are returned.

Parameters:
  `key` - Key to get adjacent nodes for.
  `cnt` - Number of adjacent nodes to get.
  `inc` - Optional inclusion set. Only nodes contained in this set may be returned. If `null`, then all nodes may be included.
  `exc` - Optional exclusion set. Only nodes not contained in this set may be returned. If `null`, then all nodes may be returned.
Returns:
  List containing adjacent nodes for given key.

#### nodes

    public List<N> nodes(@Nullable
                         Object key,
                         int cnt,
                         @Nullable
                         IgnitePredicate<N>... p)

Gets specified count of adjacent nodes for a given key. If number of nodes in consistent hash is less than specified count, then all nodes are returned.

Parameters:
  `key` - Key to get adjacent nodes for.
  `cnt` - Number of adjacent nodes to get.
  `p` - Optional predicate to filter out nodes. Nodes that don't pass the filter will be skipped.
Returns:
  List containing adjacent nodes for given key.

#### belongs

    public boolean belongs(@Nullable
                           Object key,
                           N node)

Checks if key belongs to the given node.

Parameters:
  `key` - Key to check.
  `node` - Node to check.
Returns:
  `True` if key belongs to given node.

#### belongs

    public boolean belongs(@Nullable
                           Object key,
                           @Nullable
                           Collection<N> nodes)

Checks if given key belongs to any of the given nodes.

Parameters:
  `key` - Key to check.
  `nodes` - Nodes to check (if `null` then `false` is returned).
Returns:
  `True` if key belongs to any of the given nodes.

#### belongs

    public boolean belongs(@Nullable
                           Object key,
                           int cnt,
                           N node)

Checks if node the key is mapped to or the given count of its adjacent nodes contain the node passed in.

Parameters:
  `key` - Key to check.
  `cnt` - Number of adjacent nodes to check.
  `node` - Node to check.
Returns:
  `True` if node the key is mapped to or given count of its adjacent neighbors contain the node.

#### belongs

    public boolean belongs(@Nullable
                           Object key,
                           int cnt,
                           @Nullable
                           Collection<N> nodes)

Checks if node the key is mapped to or the given count of its adjacent nodes are contained in given set of nodes.

Parameters:
  `key` - Key to check.
  `cnt` - Number of adjacent nodes to check.
  `nodes` - Nodes to check.
Returns:
  `True` if node the key is mapped to or given count of its adjacent neighbors are contained in given set of nodes.

#### hash

    protected int hash(Object o)

Gets hash code for a given object.

Parameters:
  `o` - Object to get hash code for.
Returns:
  Hash code.

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

2018 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 2.6.0
Release Date | : July 10 2018