org.gridgain.grid.util

Class GridConsistentHash<N>

java.lang.Object

org.gridgain.grid.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

Methods

Modifier and Type	Method and Description
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, GridPredicate<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, GridPredicate<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
              GridPredicate<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
            GridPredicate<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