Infinispan Distribution 5.2.6.Final-redhat-2

org.infinispan.distribution.ch
Interface ConsistentHash

All Known Implementing Classes:
DefaultConsistentHash, GroupingConsistentHash, ReplicatedConsistentHash

public interface ConsistentHash

A consistent hash algorithm implementation. Implementations would typically be constructed via a ConsistentHashFactory. A consistent hash assigns each key a list of owners; the number of owners is defined at creation time, but the consistent hash is free to return a smaller or a larger number of owners, depending on circumstances, as long as each key has at least one owner. The first element in the list of owners is the "primary owner". A key will always have a primary owner. The other owners are called "backup owners". This interface gives access to some implementation details of the consistent hash. Our consistent hashes work by splitting the hash space (the set of possible hash codes) into fixed segments and then assigning those segments to nodes dynamically. The number of segments is defined at creation time, and the mapping of keys to segments never changes. The mapping of segments to nodes can change as the membership of the cache changes. Normally application code doesn't need to know about this implementation detail, but some applications may benefit from the knowledge that all the keys that map to one segment are always located on the same server.

Since:
4.0
Author:
Manik Surtani, Mircea.Markus@jboss.com, Dan Berindei, anistor@redhat.com
See Also:
Non-BlockingStateTransferV2

Method Summary
 Hash getHashFunction()
           
 List<Address> getMembers()
          Should return the addresses of the nodes used to create this consistent hash.
 int getNumOwners()
           
 int getNumSegments()
           
 String getRoutingTableAsString()
          Returns a string containing all the segments and their associated addresses.
 int getSegment(Object key)
           
 Set<Integer> getSegmentsForOwner(Address owner)
          Returns the segments owned by a cache member.
 boolean isKeyLocalToNode(Address nodeAddress, Object key)
          Test to see whether a key is owned by a given node.
 Set<Address> locateAllOwners(Collection<Object> keys)
          The logical equivalent of calling locateOwners(java.lang.Object) multiple times for each key in the collection of keys and merging the results.
 List<Address> locateOwners(Object key)
          Finds all the owners of a key.
 List<Address> locateOwnersForSegment(int segmentId)
           
 Address locatePrimaryOwner(Object key)
          Should be equivalent to return the first element of locateOwners(java.lang.Object).
 Address locatePrimaryOwnerForSegment(int segmentId)
           
 

Method Detail

getNumOwners

int getNumOwners()
Returns:
The configured number of owners for each key. Note that {code @getOwners(key)} may return a different number of owners.

getHashFunction

Hash getHashFunction()

getNumSegments

int getNumSegments()
Returns:
The actual number of hash space segments. Note that it may not be the same as the number of segments passed in at creation time.

getMembers

List<Address> getMembers()
Should return the addresses of the nodes used to create this consistent hash.

Returns:
set of node addresses.

locatePrimaryOwner

Address locatePrimaryOwner(Object key)
Should be equivalent to return the first element of locateOwners(java.lang.Object). Useful as a performance optimization, as this is a frequently needed information.

Parameters:
key - key to locate
Returns:
the address of the owner

locateOwners

List<Address> locateOwners(Object key)
Finds all the owners of a key. The first element in the returned list is the primary owner.

Parameters:
key - key to locate
Returns:
An unmodifiable list of addresses where the key resides. Will never be null, and it will always have at least 1 element.

locateAllOwners

Set<Address> locateAllOwners(Collection<Object> keys)
The logical equivalent of calling locateOwners(java.lang.Object) multiple times for each key in the collection of keys and merging the results. Implementations may be optimised for such a bulk lookup.

Parameters:
keys - keys to locate.
Returns:
set of nodes that own at least one of the keys.

isKeyLocalToNode

boolean isKeyLocalToNode(Address nodeAddress,
                         Object key)
Test to see whether a key is owned by a given node.

Parameters:
nodeAddress - address of the node to test
key - key to test
Returns:
true if the key is mapped to the address; false otherwise

getSegment

int getSegment(Object key)
Returns:
The hash space segment that a key maps to.

locateOwnersForSegment

List<Address> locateOwnersForSegment(int segmentId)
Returns:
All the nodes that own a given hash space segment. The returned list is unmodifiable.

locatePrimaryOwnerForSegment

Address locatePrimaryOwnerForSegment(int segmentId)
Returns:
The primary owner of a given hash space segment. This is equivalent to locateOwnersForSegment(segmentId).get(0) but is more efficient

getSegmentsForOwner

Set<Integer> getSegmentsForOwner(Address owner)
Returns the segments owned by a cache member.

Parameters:
owner - the address of the member
Returns:
a non-nul set of segment IDs

getRoutingTableAsString

String getRoutingTableAsString()
Returns a string containing all the segments and their associated addresses.


Infinispan Distribution 5.2.6.Final-redhat-2

Copyright © 2013 JBoss, a division of Red Hat. All Rights Reserved.