org.infinispan.distribution
Interface ConsistentHash

All Known Implementing Classes:

AbstractConsistentHash, DefaultConsistentHash, ExperimentalDefaultConsistentHash, UnionConsistentHash

public interface ConsistentHash

A consistent hash algorithm implementation. Implementations would typically be constructed via reflection so should implement a public, no-arg constructor.

Since:

4.0

Author:

Manik Surtani

Method Summary

List<Address>	getCaches() Should return a collection of cache addresses in the cluster.
int	getDistance(Address a1, Address a2) Calculates the logical distance between two addresses.
int	getHashId(Address a) Returns the value between 0 and the hash space limit, or hash id, for a particular address.
int	getHashSpace() Returns the hash space constant for this consistent hash algorithm class.
boolean	isAdjacent(Address a1, Address a2) Tests whether two addresses are logically next to each other in the hash space.
boolean	isKeyLocalToAddress(Address a, Object key, int replCount) Test to see whether a key is mapped to a given address.
List<Address>	locate(Object key, int replCount) Locates a key, given a replication count (number of copies).
Map<Object,List<Address>>	locateAll(Collection<Object> keys, int replCount) The logical equivalent of calling locate(Object, int) multiple times for each key in the collection of keys.
void	setCaches(List<Address> caches) Sets the collection of cache addresses in the cluster.

Method Detail

setCaches

void setCaches(List<Address> caches)

Sets the collection of cache addresses in the cluster. The implementation should store these internally and use these to locate keys.

Parameters:

caches - caches in cluster.

getCaches

List<Address> getCaches()

Should return a collection of cache addresses in the cluster.

Returns:

collection of cache addresses

locate

List<Address> locate(Object key,
                     int replCount)

Locates a key, given a replication count (number of copies).

Parameters:

key - key to locate

replCount - replication count (number of copies)

Returns:

a list of addresses where the key resides, where this list is a subset of the addresses set in setCaches(java.util.List). Should never be null, and should contain replCount elements or the max number of caches available, whichever is smaller.

locateAll

Map<Object,List<Address>> locateAll(Collection<Object> keys,
                                    int replCount)

The logical equivalent of calling locate(Object, int) multiple times for each key in the collection of keys. Implementations may be optimised for such a bulk lookup, or may just repeatedly call locate(Object, int).

Parameters:

keys - keys to locate

replCount - replication count (number of copies) for each key

Returns:

Map of locations, keyed on key.

getDistance

int getDistance(Address a1,
                Address a2)

Calculates the logical distance between two addresses. This distance is based on where the addresses lie in the hash space.

Parameters:

a1 - address to test

a2 - address to test

Returns:

the distance between the 2 nodes. Always a positive number, where the distance between a1 and itself is 0. The distance between a1 and the next adjacent node is 1 and teh distance between a1 and the previous adjacent node is caches.size() - 1. A -1 may be returned if either of the addresses do not exist.

isAdjacent

boolean isAdjacent(Address a1,
                   Address a2)

Tests whether two addresses are logically next to each other in the hash space.

Parameters:

a1 - address to test

a2 - address to test

Returns:

true if adjacent, false if not

isKeyLocalToAddress

boolean isKeyLocalToAddress(Address a,
                            Object key,
                            int replCount)

Test to see whether a key is mapped to a given address.

Parameters:

a - address to test

key - key to test

replCount - repl count

Returns:

true if the key is mapped to the address; false otherwise

getHashId

int getHashId(Address a)

Returns the value between 0 and the hash space limit, or hash id, for a particular address. If there's no such value for an address, this method will return -1.

Returns:

An int between 0 and hash space if the address is present in the hash wheel, otherwise it returns -1.

getHashSpace

int getHashSpace()

Returns the hash space constant for this consistent hash algorithm class. This integer is often used as modulus for arithmetic operations within the algorithm, for example, limiting the range of possible hash values.

Returns:

A positive integer containing the hash space constant or 0 is not supported by implementation.