org.apache.ignite.cache.affinity.rendezvous

## Class RendezvousAffinityFunction

- java.lang.Object
- - org.apache.ignite.cache.affinity.rendezvous.RendezvousAffinityFunction

- All Implemented Interfaces:
    Serializable, AffinityFunction

      public class RendezvousAffinityFunction
      extends Object
      implements AffinityFunction, Serializable

  Affinity function for partitioned cache based on Highest Random Weight algorithm. This function supports the following configuration:
  - `partitions` - Number of partitions to spread across nodes.
  - `excludeNeighbors` - If set to `true`, will exclude same-host-neighbors from being backups of each other. This flag can be ignored in cases when topology has no enough nodes for assign backups. Note that `backupFilter` is ignored if `excludeNeighbors` is set to `true`.
  - `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
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DFLT_PARTITION_COUNT` Default number of partitions.

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `List<ClusterNode>` | `assignPartition(int part, List<ClusterNode> nodes, int backups, @Nullable Map<UUID,Collection<ClusterNode>> neighborhoodCache)` Returns collection of nodes (primary first) for specified partition.
    `List<List<ClusterNode>>` | `assignPartitions(AffinityFunctionContext affCtx)` Gets affinity nodes for a partition.
    `static int` | `calculateMask(int parts)` Helper method to calculates mask.
    `static int` | `calculatePartition(Object key, int mask, int parts)` Helper method to calculate partition.
    `@Nullable IgniteBiPredicate<ClusterNode,List<ClusterNode>>` | `getAffinityBackupFilter()` Gets optional backup filter.
    `@Nullable IgniteBiPredicate<ClusterNode,ClusterNode>` | `getBackupFilter()` Gets optional backup filter.
    `int` | `getPartitions()` Gets total number of key partitions.
    `boolean` | `isExcludeNeighbors()` Checks flag to exclude same-host-neighbors from being backups of each other (default is `false`).
    `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.
    `Object` | `resolveNodeHash(ClusterNode node)` Resolves node hash.
    `RendezvousAffinityFunction` | `setAffinityBackupFilter(@Nullable IgniteBiPredicate<ClusterNode,List<ClusterNode>> affinityBackupFilter)` Sets optional backup filter.
    `RendezvousAffinityFunction` | `setBackupFilter(@Nullable IgniteBiPredicate<ClusterNode,ClusterNode> backupFilter)` Deprecated. Use `affinityBackupFilter` instead.
    `RendezvousAffinityFunction` | `setExcludeNeighbors(boolean exclNeighbors)` Sets flag to exclude same-host-neighbors from being backups of each other (default is `false`).
    `RendezvousAffinityFunction` | `setPartitions(int parts)` Sets total number of partitions.If the number of partitions is a power of two, the PowerOfTwo hashing method will be used.
    `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

  - ### Constructor Detail

    - #### RendezvousAffinityFunction

          public RendezvousAffinityFunction()

      Empty constructor with all defaults.

    - #### RendezvousAffinityFunction

          public RendezvousAffinityFunction(boolean exclNeighbors)

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

      Note that `backupFilter` is ignored if `excludeNeighbors` is set to `true`.

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

    - #### RendezvousAffinityFunction

          public RendezvousAffinityFunction(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 `backupFilter` is ignored if `excludeNeighbors` is set to `true`.

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

    - #### RendezvousAffinityFunction

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

      Initializes optional counts for replicas and backups.

      Note that `backupFilter` is ignored if `excludeNeighbors` is set to `true`.

      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 `backupFilter` is ignored if `excludeNeighbors` is set to `true`.

  - ### Method Detail

    - #### calculateMask

          public static int calculateMask(int parts)

      Helper method to calculates mask.
      Parameters:
        `parts` - Number of partitions.
      Returns:
        Mask to use in calculation when partitions count is power of 2.

    - #### calculatePartition

          public static int calculatePartition(Object key,
                                               int mask,
                                               int parts)

      Helper method to calculate partition.
      Parameters:
        `key` - – Key to get partition for.
        `mask` - Mask to use in calculation when partitions count is power of 2.
        `parts` - Number of partitions.
      Returns:
        Partition number for a given key.

    - #### 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.

      For fully replicated caches this method works the same way as a partitioned cache.

      Returns:
        Total partition count.

    - #### setPartitions

          public RendezvousAffinityFunction setPartitions(int parts)

      Sets total number of partitions.If the number of partitions is a power of two, the PowerOfTwo hashing method will be used. Otherwise the Standard hashing method will be applied.
      Parameters:
        `parts` - Total number of partitions.
      Returns:
        `this` for chaining.

    - #### getBackupFilter

          @Nullable
          public @Nullable 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 `backupFilter` is ignored if `excludeNeighbors` is set to `true`.

      Returns:
        Optional backup filter.

    - #### setBackupFilter

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

      Deprecated. Use `affinityBackupFilter` instead.
      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 `backupFilter` is ignored if `excludeNeighbors` is set to `true`.

      Parameters:
        `backupFilter` - Optional backup filter.
      Returns:
        `this` for chaining.

    - #### getAffinityBackupFilter

          @Nullable
          public @Nullable IgniteBiPredicate<ClusterNode,List<ClusterNode>> getAffinityBackupFilter()

      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 a node being tested, and the second parameter is a list of nodes that are already assigned for a given partition (primary node is the first in the list).

      Note that `affinityBackupFilter` is ignored if `excludeNeighbors` is set to `true`.

      Returns:
        Optional backup filter.

    - #### setAffinityBackupFilter

          public RendezvousAffinityFunction setAffinityBackupFilter(@Nullable
                                                                    @Nullable IgniteBiPredicate<ClusterNode,List<ClusterNode>> affinityBackupFilter)

      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 a node being tested, and the second parameter is a list of nodes that are already assigned for a given partition (primary node is the first in the list).

      Note that `affinityBackupFilter` is ignored if `excludeNeighbors` is set to `true`.

      For an example filter, see `ClusterNodeAttributeAffinityBackupFilter`.

      Parameters:
        `affinityBackupFilter` - Optional backup filter.
      Returns:
        `this` for chaining.

    - #### isExcludeNeighbors

          public boolean isExcludeNeighbors()

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

      Note that `backupFilter` is ignored if `excludeNeighbors` is set to `true`.

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

    - #### setExcludeNeighbors

          public RendezvousAffinityFunction setExcludeNeighbors(boolean exclNeighbors)

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

      Note that `backupFilter` is ignored if `excludeNeighbors` is set to `true`.

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

    - #### resolveNodeHash

          public Object resolveNodeHash(ClusterNode node)

      Resolves node hash.
      Parameters:
        `node` - Cluster node;
      Returns:
        Node hash.

    - #### assignPartition

          public List<ClusterNode> assignPartition(int part,
                                                   List<ClusterNode> nodes,
                                                   int backups,
                                                   @Nullable
                                                   @Nullable Map<UUID,Collection<ClusterNode>> neighborhoodCache)

      Returns collection of nodes (primary first) for specified partition.
      Parameters:
        `part` - Partition.
        `nodes` - Nodes.
        `backups` - Number of backups.
        `neighborhoodCache` - Neighborhood.
      Returns:
        Assignment.

    - #### 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 `AffinityFunction`

    - #### 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 `AffinityFunction`
      Returns:
        Total partition count.

    - #### 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 `AffinityFunction`
      Parameters:
        `key` - Key to get partition for.
      Returns:
        Partition number for a given key.

    - #### assignPartitions

          public List<List<ClusterNode>> assignPartitions(AffinityFunctionContext affCtx)

      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 `AffinityFunction`
      Parameters:
        `affCtx` - 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.

    - #### 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 `AffinityFunction`
      Parameters:
        `nodeId` - ID of node to remove.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

2022 Copyright © Apache Software Foundation
| Follow @ApacheIgnite
Ignite Database and Caching Platform | : ver. 2.12.0
Release Date | : January 10 2022