org.apache.ignite.cache.affinity.consistenthash

## Class CacheConsistentHashAffinityFunction

- java.lang.Object
- - org.apache.ignite.cache.affinity.consistenthash.CacheConsistentHashAffinityFunction

All Implemented Interfaces:
  Serializable, CacheAffinityFunction

    public class CacheConsistentHashAffinityFunction
    extends Object
    implements CacheAffinityFunction

Affinity function for partitioned cache. This function supports the following configuration:

- `backups` - Use this flag to control how many back up nodes will be assigned to every key. The default value is `0`.
- `replicas` - Generally the more replicas a node gets, the more key assignments it will receive. You can configure different number of replicas for a node by setting user attribute with name `getReplicaCountAttributeName()` to some number. Default value is `512` defined by `DFLT_REPLICA_COUNT` constant.
- `backupFilter` - Optional filter for back up nodes. If provided, then only nodes that pass this filter will be selected as backup nodes. If not provided, then primary and backup nodes will be selected out of all nodes available for this cache.

Cache affinity can be configured for individual caches via `CacheConfiguration.getAffinity()` method.

See Also:
  Serialized Form

### Field Summary

Fields
`static int` `DFLT_PARTITION_COUNT` Default number of partitions.
`static int` `DFLT_REPLICA_COUNT` Default replica count for partitioned caches.
`static String` `DFLT_REPLICA_COUNT_ATTR_NAME` Name of node attribute to specify number of replicas for a node.

### Constructor Summary

Constructors
Constructor and Description
`CacheConsistentHashAffinityFunction()` Empty constructor with all defaults.
`CacheConsistentHashAffinityFunction(boolean exclNeighbors)` Initializes affinity with flag to exclude same-host-neighbors from being backups of each other and specified number of backups.
`CacheConsistentHashAffinityFunction(boolean exclNeighbors, int parts)` Initializes affinity with flag to exclude same-host-neighbors from being backups of each other, and specified number of backups and partitions.
`CacheConsistentHashAffinityFunction(int parts, IgniteBiPredicate<ClusterNode,ClusterNode> backupFilter)` Initializes optional counts for replicas and backups.

### Method Summary

Methods
`List<List<ClusterNode>>` `assignPartitions(CacheAffinityFunctionContext ctx)` Gets affinity nodes for a partition.
`IgniteBiPredicate<ClusterNode,ClusterNode>` `getBackupFilter()` Gets optional backup filter.
`int` `getDefaultReplicas()` Gets default count of virtual replicas in consistent hash ring.
`CacheAffinityNodeHashResolver` `getHashIdResolver()` Gets hash ID resolver for nodes.
`int` `getPartitions()` Gets total number of key partitions.
`String` `getReplicaCountAttributeName()` Gets optional attribute name for replica count.
`boolean` `isExcludeNeighbors()` Checks flag to exclude same-host-neighbors from being backups of each other (default is `false`).
`Collection<ClusterNode>` `nodes(int part, Collection<ClusterNode> nodes, int backups)` Assigns nodes to one partition.
`int` `partition(Object key)` Gets partition number for a given key starting from `0`.
`int` `partitions()` Gets total number of partitions available.
`void` `removeNode(UUID nodeId)` Removes node from affinity.
`void` `reset()` Resets cache affinity to its initial state.
`void` `setBackupFilter(IgniteBiPredicate<ClusterNode,ClusterNode> backupFilter)` Sets optional backup filter.
`void` `setDefaultReplicas(int replicas)` Sets default count of virtual replicas in consistent hash ring.
`void` `setExcludeNeighbors(boolean exclNeighbors)` Sets flag to exclude same-host-neighbors from being backups of each other (default is `false`).
`void` `setHashIdResolver(CacheAffinityNodeHashResolver hashIdRslvr)` Sets hash ID resolver for nodes.
`void` `setPartitions(int parts)` Sets total number of partitions.
`void` `setReplicaCountAttributeName(String attrName)` Sets optional attribute name for replica count.
`String` `toString()`

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

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

### Field Detail

#### DFLT_PARTITION_COUNT

    public static final int DFLT_PARTITION_COUNT

Default number of partitions.

See Also:
  Constant Field Values

#### DFLT_REPLICA_COUNT

    public static final int DFLT_REPLICA_COUNT

Default replica count for partitioned caches.

See Also:
  Constant Field Values

#### DFLT_REPLICA_COUNT_ATTR_NAME

    public static final String DFLT_REPLICA_COUNT_ATTR_NAME

Name of node attribute to specify number of replicas for a node. Default value is `gg:affinity:node:replicas`.

See Also:
  Constant Field Values

### Constructor Detail

#### CacheConsistentHashAffinityFunction

    public CacheConsistentHashAffinityFunction()

Empty constructor with all defaults.

#### CacheConsistentHashAffinityFunction

    public CacheConsistentHashAffinityFunction(boolean exclNeighbors)

Initializes affinity with flag to exclude same-host-neighbors from being backups of each other and specified number of backups.

Note that `excludeNeighbors` parameter is ignored if `#getBackupFilter()` is set.

Parameters:
  `exclNeighbors` - `True` if nodes residing on the same host may not act as backups of each other.

#### CacheConsistentHashAffinityFunction

    public CacheConsistentHashAffinityFunction(boolean exclNeighbors,
                                       int parts)

Initializes affinity with flag to exclude same-host-neighbors from being backups of each other, and specified number of backups and partitions.

Note that `excludeNeighbors` parameter is ignored if `#getBackupFilter()` is set.

Parameters:
  `exclNeighbors` - `True` if nodes residing on the same host may not act as backups of each other.
  `parts` - Total number of partitions.

#### CacheConsistentHashAffinityFunction

    public CacheConsistentHashAffinityFunction(int parts,
                                       @Nullable
                                       IgniteBiPredicate<ClusterNode,ClusterNode> backupFilter)

Initializes optional counts for replicas and backups.

Note that `excludeNeighbors` parameter is ignored if `backupFilter` is set.

Parameters:
  `parts` - Total number of partitions.
  `backupFilter` - Optional back up filter for nodes. If provided, backups will be selected from all nodes that pass this filter. First argument for this filter is primary node, and second argument is node being tested.

  Note that `excludeNeighbors` parameter is ignored if `backupFilter` is set.

### Method Detail

#### getDefaultReplicas

    public int getDefaultReplicas()

Gets default count of virtual replicas in consistent hash ring.

To determine node replicas, node attribute with `getReplicaCountAttributeName()` name will be checked first. If it is absent, then this value will be used.

Returns:
  Count of virtual replicas in consistent hash ring.

#### setDefaultReplicas

    public void setDefaultReplicas(int replicas)

Sets default count of virtual replicas in consistent hash ring.

To determine node replicas, node attribute with `getReplicaCountAttributeName()` name will be checked first. If it is absent, then this value will be used.

Parameters:
  `replicas` - Count of virtual replicas in consistent hash ring.s

#### getPartitions

    public int getPartitions()

Gets total number of key partitions. To ensure that all partitions are equally distributed across all nodes, please make sure that this number is significantly larger than a number of nodes. Also, partition size should be relatively small. Try to avoid having partitions with more than quarter million keys.

Note that for fully replicated caches this method should always return `1`.

Returns:
  Total partition count.

#### setPartitions

    public void setPartitions(int parts)

Sets total number of partitions.

Parameters:
  `parts` - Total number of partitions.

#### getHashIdResolver

    public CacheAffinityNodeHashResolver getHashIdResolver()

Gets hash ID resolver for nodes. This resolver is used to provide alternate hash ID, other than node ID.

Node IDs constantly change when nodes get restarted, which causes them to be placed on different locations in the hash ring, and hence causing repartitioning. Providing an alternate hash ID, which survives node restarts, puts node on the same location on the hash ring, hence minimizing required repartitioning.

Returns:
  Hash ID resolver.

#### setHashIdResolver

    public void setHashIdResolver(CacheAffinityNodeHashResolver hashIdRslvr)

Sets hash ID resolver for nodes. This resolver is used to provide alternate hash ID, other than node ID.

Node IDs constantly change when nodes get restarted, which causes them to be placed on different locations in the hash ring, and hence causing repartitioning. Providing an alternate hash ID, which survives node restarts, puts node on the same location on the hash ring, hence minimizing required repartitioning.

Parameters:
  `hashIdRslvr` - Hash ID resolver.

#### getBackupFilter

    @Nullable
    public IgniteBiPredicate<ClusterNode,ClusterNode> getBackupFilter()

Gets optional backup filter. If not `null`, backups will be selected from all nodes that pass this filter. First node passed to this filter is primary node, and second node is a node being tested.

Note that `excludeNeighbors` parameter is ignored if `backupFilter` is set.

Returns:
  Optional backup filter.

#### setBackupFilter

    public void setBackupFilter(@Nullable
                       IgniteBiPredicate<ClusterNode,ClusterNode> backupFilter)

Sets optional backup filter. If provided, then backups will be selected from all nodes that pass this filter. First node being passed to this filter is primary node, and second node is a node being tested.

Note that `excludeNeighbors` parameter is ignored if `backupFilter` is set.

Parameters:
  `backupFilter` - Optional backup filter.

#### getReplicaCountAttributeName

    public String getReplicaCountAttributeName()

Gets optional attribute name for replica count. If not provided, the default is `DFLT_REPLICA_COUNT_ATTR_NAME`.

Returns:
  User attribute name for replica count for a node.

#### setReplicaCountAttributeName

    public void setReplicaCountAttributeName(String attrName)

Sets optional attribute name for replica count. If not provided, the default is `DFLT_REPLICA_COUNT_ATTR_NAME`.

Parameters:
  `attrName` - User attribute name for replica count for a node.

#### isExcludeNeighbors

    public boolean isExcludeNeighbors()

Checks flag to exclude same-host-neighbors from being backups of each other (default is `false`).

Note that `excludeNeighbors` parameter is ignored if `#getBackupFilter()` is set.

Returns:
  `True` if nodes residing on the same host may not act as backups of each other.

#### setExcludeNeighbors

    public void setExcludeNeighbors(boolean exclNeighbors)

Sets flag to exclude same-host-neighbors from being backups of each other (default is `false`).

Note that `excludeNeighbors` parameter is ignored if `#getBackupFilter()` is set.

Parameters:
  `exclNeighbors` - `True` if nodes residing on the same host may not act as backups of each other.

#### assignPartitions

    public List<List<ClusterNode>> assignPartitions(CacheAffinityFunctionContext ctx)

Gets affinity nodes for a partition. In case of replicated cache, all returned nodes are updated in the same manner. In case of partitioned cache, the returned list should contain only the primary and back up nodes with primary node being always first.

Note that partitioned affinity must obey the following contract: given that node `N` is primary for some key `K`, if any other node(s) leave grid and no node joins grid, node `N` will remain primary for key `K`.

Specified by:
  `assignPartitions` in interface `CacheAffinityFunction`
Parameters:
  `ctx` - Affinity function context. Will provide all required information to calculate new partition assignments.
Returns:
  Unmodifiable list indexed by partition number. Each element of array is a collection in which first node is a primary node and other nodes are backup nodes.

#### nodes

    public Collection<ClusterNode> nodes(int part,
                                Collection<ClusterNode> nodes,
                                int backups)

Assigns nodes to one partition.

Parameters:
  `part` - Partition to assign nodes for.
  `nodes` - Cache topology nodes.
Returns:
  Assigned nodes, first node is primary, others are backups.

#### partition

    public int partition(Object key)

Gets partition number for a given key starting from `0`. Partitioned caches should make sure that keys are about evenly distributed across all partitions from `0` to `partition count` for best performance.

Note that for fully replicated caches it is possible to segment key sets among different grid node groups. In that case each node group should return a unique partition number. However, unlike partitioned cache, mappings of keys to nodes in replicated caches are constant and a node cannot migrate from one partition to another.

Specified by:
  `partition` in interface `CacheAffinityFunction`
Parameters:
  `key` - Key to get partition for.
Returns:
  Partition number for a given key.

#### partitions

    public int partitions()

Gets total number of partitions available. All caches should always provide correct partition count which should be the same on all participating nodes. Note that partitions should always be numbered from `0` inclusively to `N` exclusively without any gaps.

Specified by:
  `partitions` in interface `CacheAffinityFunction`
Returns:
  Total partition count.

#### reset

    public void reset()

Resets cache affinity to its initial state. This method will be called by the system any time the affinity has been sent to remote node where it has to be reinitialized. If your implementation of affinity function has no initialization logic, leave this method empty.

Specified by:
  `reset` in interface `CacheAffinityFunction`

#### removeNode

    public void removeNode(UUID nodeId)

Removes node from affinity. This method is called when it is safe to remove left node from affinity mapping.

Specified by:
  `removeNode` in interface `CacheAffinityFunction`
Parameters:
  `nodeId` - ID of node to remove.

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.0.0-RC1
Release Date | : February 17 2015