ConsistentHash

```
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. The first element in the list of owners is the "primary owner". The other owners are called "backup owners". Some implementations guarantee that there will always be a primary owner, others do not. 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

See Also:

Non-BlockingStateTransferV2

Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`default java.util.Map<Address,java.lang.Float>`	`getCapacityFactors()` The capacity factor of each member.
`default Hash`	`getHashFunction()` Deprecated. Since 8.2, the `Hash` is optional - replaced in the configuration by the `KeyPartitioner`
`java.util.List<Address>`	`getMembers()` Should return the addresses of the nodes used to create this consistent hash.
`int`	`getNumOwners()` Deprecated. Since 9.1, it should not be used to obtain the number of owners of a particular key.
`int`	`getNumSegments()`
`java.util.Set<java.lang.Integer>`	`getPrimarySegmentsForOwner(Address owner)` Returns the segments that this cache member is the primary owner for.
`java.lang.String`	`getRoutingTableAsString()` Returns a string containing all the segments and their associated addresses.
`int`	`getSegment(java.lang.Object key)` Deprecated. Since 9.0, please use `KeyPartitioner.getSegment(Object)` or `LocalizedCacheTopology.getSegment(Object)` instead.
`java.util.Set<java.lang.Integer>`	`getSegmentsForOwner(Address owner)` Returns the segments owned by a cache member.
`default boolean`	`isKeyLocalToNode(Address nodeAddress, java.lang.Object key)` Deprecated. Since 9.0, please use `LocalizedCacheTopology.isReadOwner(Object)` and `LocalizedCacheTopology.isWriteOwner(Object)` instead.
`default boolean`	`isReplicated()`
`default boolean`	`isSegmentLocalToNode(Address nodeAddress, int segmentId)` Check if a segment is local to a given member.
`default java.util.Set<Address>`	`locateAllOwners(java.util.Collection<java.lang.Object> keys)` Deprecated. Since 9.0, please use `LocalizedCacheTopology.getWriteOwners(Collection)` instead.
`default java.util.List<Address>`	`locateOwners(java.lang.Object key)` Deprecated. Since 9.0, please use `LocalizedCacheTopology.getDistribution(Object)` instead.
`java.util.List<Address>`	`locateOwnersForSegment(int segmentId)`
`default Address`	`locatePrimaryOwner(java.lang.Object key)` Deprecated. Since 9.0, please use `LocalizedCacheTopology.getDistribution(Object)` instead.
`Address`	`locatePrimaryOwnerForSegment(int segmentId)`
`default ConsistentHash`	`remapAddresses(java.util.function.UnaryOperator<Address> remapper)` Returns a new ConsistentHash with the addresses remapped according to the provided `UnaryOperator`.
`default void`	`toScopedState(ScopedPersistentState state)` Writes this ConsistentHash to the specified scoped state.

- Method Detail
  - getNumOwners
```
@Deprecated
int getNumOwners()
```
    Deprecated. Since 9.1, it should not be used to obtain the number of owners of a particular key.
    
    Returns:
    
    The configured number of owners. Note that the actual number of owners of each key may be different.
  - getHashFunction
```
@Deprecated
default Hash getHashFunction()
```
    Deprecated. Since 8.2, the Hash is optional - replaced in the configuration by the KeyPartitioner
  - 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
```
java.util.List<Address> getMembers()
```
    Should return the addresses of the nodes used to create this consistent hash.
    
    Returns:
    
    set of node addresses.
  - locatePrimaryOwner
```
@Deprecated
default Address locatePrimaryOwner(java.lang.Object key)
```
    Deprecated. Since 9.0, please use LocalizedCacheTopology.getDistribution(Object) instead.
    
    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
```
@Deprecated
default java.util.List<Address> locateOwners(java.lang.Object key)
```
    Deprecated. Since 9.0, please use LocalizedCacheTopology.getDistribution(Object) instead.
    
    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
```
@Deprecated
default java.util.Set<Address> locateAllOwners(java.util.Collection<java.lang.Object> keys)
```
    Deprecated. Since 9.0, please use LocalizedCacheTopology.getWriteOwners(Collection) instead.
  - isKeyLocalToNode
```
@Deprecated
default boolean isKeyLocalToNode(Address nodeAddress,
                                             java.lang.Object key)
```
    Deprecated. Since 9.0, please use LocalizedCacheTopology.isReadOwner(Object) and LocalizedCacheTopology.isWriteOwner(Object) instead.
    
    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
```
@Deprecated
int getSegment(java.lang.Object key)
```
    Deprecated. Since 9.0, please use KeyPartitioner.getSegment(Object) or LocalizedCacheTopology.getSegment(Object) instead.
    
    Returns:
    
    The hash space segment that a key maps to.
  - locateOwnersForSegment
```
java.util.List<Address> locateOwnersForSegment(int segmentId)
```
    Returns:
    
    All the nodes that own a given hash space segment, first address is the primary owner. 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
  - isSegmentLocalToNode
```
default boolean isSegmentLocalToNode(Address nodeAddress,
                                     int segmentId)
```
    Check if a segment is local to a given member.
    Implementation note: normally key-based method are implemented based on segment-based methods. Here, however, we need a default implementation for the segment-based method for backwards-compatibility reasons.
    
    Since:
    
    8.2
  - isReplicated
```
default boolean isReplicated()
```
    Returns:
    
    true if every member owns every segment. This allows callers to skip computing the segment of a key in some cases.
  - getSegmentsForOwner
```
java.util.Set<java.lang.Integer> getSegmentsForOwner(Address owner)
```
    Returns the segments owned by a cache member.
    
    Parameters:
    
    owner - the address of the member
    
    Returns:
    
    a non-null set of segment IDs, may or may not be unmodifiable, which shouldn't be modified by caller
  - getPrimarySegmentsForOwner
```
java.util.Set<java.lang.Integer> getPrimarySegmentsForOwner(Address owner)
```
    Returns the segments that this cache member is the primary owner for.
    
    Parameters:
    
    owner - the address of the member
    
    Returns:
    
    a non-null set of segment IDs, may or may not be unmodifiable, which shouldn't be modified by caller
  - getRoutingTableAsString
```
java.lang.String getRoutingTableAsString()
```
    Returns a string containing all the segments and their associated addresses.
  - toScopedState
```
default void toScopedState(ScopedPersistentState state)
```
    Writes this ConsistentHash to the specified scoped state. Before invoking this method, the ConsistentHash addresses will have to be replaced with their corresponding PersistentUUIDs
    
    Parameters:
    
    state - the state to which this ConsistentHash will be written
  - remapAddresses
```
default ConsistentHash remapAddresses(java.util.function.UnaryOperator<Address> remapper)
```
    Returns a new ConsistentHash with the addresses remapped according to the provided UnaryOperator. If an address cannot me remapped (i.e. the remapper returns null) this method should return null.
    
    Parameters:
    
    remapper - the remapper which given an address replaces it with another one
    
    Returns:
    
    the remapped ConsistentHash or null if one of the remapped addresses is null
  - getCapacityFactors
```
default java.util.Map<Address,java.lang.Float> getCapacityFactors()
```
    The capacity factor of each member. Determines the relative capacity of each node compared to the others. If null, all the members are assumed to have a capacity factor of 1.

Interface ConsistentHash

Method Summary

Method Detail

getNumOwners

getHashFunction

getNumSegments

getMembers

locatePrimaryOwner

locateOwners

locateAllOwners

isKeyLocalToNode

getSegment

locateOwnersForSegment

locatePrimaryOwnerForSegment

isSegmentLocalToNode

isReplicated

getSegmentsForOwner

getPrimarySegmentsForOwner

getRoutingTableAsString

toScopedState

remapAddresses

getCapacityFactors