Package org.apache.ignite.cache.affinity

## Interface Affinity<K>

-     public interface Affinity<K>

  Provides affinity information to detect which node is primary and which nodes are backups for a partitioned or replicated cache. You can get an instance of this interface by calling `Ignite.affinity(cacheName)` method.

  Mapping of a key to a node is a three-step operation. First step will get an affinity key for given key using `AffinityKeyMapper`. If mapper is not specified, the original key will be used. Second step will map affinity key to partition using `AffinityFunction.partition(Object)` method. Third step will map obtained partition to nodes for current grid topology version.

  Interface provides various `'mapKeysToNodes(..)'` methods which provide node affinity mapping for given keys. All `'mapKeysToNodes(..)'` methods are not transactional and will not enlist keys into ongoing transaction.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Object` | `affinityKey​(K key)` | Maps passed in key to a key which will be used for node affinity.
    `int[]` | `allPartitions​(ClusterNode n)` | Gets partition ids for which given cluster node has any ownership (either primary or backup).
    `int[]` | `backupPartitions​(ClusterNode n)` | Gets partition ids for which given cluster node has backup ownership.
    `boolean` | `isBackup​(ClusterNode n, K key)` | Returns `true` if local node is one of the backup nodes for given key.
    `boolean` | `isPrimary​(ClusterNode n, K key)` | Returns `true` if given node is the primary node for given key.
    `boolean` | `isPrimaryOrBackup​(ClusterNode n, K key)` | Returns `true` if local node is primary or one of the backup nodes
    `Map<ClusterNode,​Collection<K>>` | `mapKeysToNodes​(Collection<? extends K> keys)` | This method provides ability to detect which keys are mapped to which nodes.
    `@Nullable ClusterNode` | `mapKeyToNode​(K key)` | This method provides ability to detect to which primary node the given key is mapped.
    `Collection<ClusterNode>` | `mapKeyToPrimaryAndBackups​(K key)` | Gets primary and backup nodes for the key.
    `Map<Integer,​ClusterNode>` | `mapPartitionsToNodes​(Collection<Integer> parts)` | Gets primary nodes for the given partitions.
    `ClusterNode` | `mapPartitionToNode​(int part)` | Gets primary node for the given partition.
    `Collection<ClusterNode>` | `mapPartitionToPrimaryAndBackups​(int part)` | Gets primary and backup nodes for partition.
    `int` | `partition​(K key)` | Gets partition id for the given key.
    `int` | `partitions()` | Gets number of partitions in cache according to configured affinity function.
    `int[]` | `primaryPartitions​(ClusterNode n)` | Gets partition ids for which the given cluster node has primary ownership.

- - ### Method Detail

    - #### partitions

          int partitions()

      Gets number of partitions in cache according to configured affinity function.
      Returns:
        Number of cache partitions.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.
      See Also:
        `AffinityFunction`, `CacheConfiguration.getAffinity()`, `CacheConfiguration.setAffinity(AffinityFunction)`

    - #### partition

          int partition​(K key)

      Gets partition id for the given key.
      Parameters:
        `key` - Key to get partition id for.
      Returns:
        Partition id.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.
      See Also:
        `AffinityFunction`, `CacheConfiguration.getAffinity()`, `CacheConfiguration.setAffinity(AffinityFunction)`

    - #### isPrimary

          boolean isPrimary​(ClusterNode n,
                            K key)

      Returns `true` if given node is the primary node for given key.
      Parameters:
        `n` - Node to check.
        `key` - Key to check.
      Returns:
        `True` if local node is the primary node for given key.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.

    - #### isBackup

          boolean isBackup​(ClusterNode n,
                           K key)

      Returns `true` if local node is one of the backup nodes for given key.
      Parameters:
        `n` - Node to check.
        `key` - Key to check.
      Returns:
        `True` if local node is one of the backup nodes for given key.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.

    - #### isPrimaryOrBackup

          boolean isPrimaryOrBackup​(ClusterNode n,
                                    K key)

      Returns `true` if local node is primary or one of the backup nodes

      This method is essentially equivalent to calling "`isPrimary(ClusterNode, Object)` || `isBackup(ClusterNode, Object)`)", however it is more efficient as it makes both checks at once.

      Parameters:
        `n` - Node to check.
        `key` - Key to check.
      Returns:
        `True` if local node is primary or backup for given key.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.

    - #### primaryPartitions

          int[] primaryPartitions​(ClusterNode n)

      Gets partition ids for which the given cluster node has primary ownership.
      Parameters:
        `n` - Cluster node.
      Returns:
        Partition ids for which given cluster node has primary ownership.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.
      See Also:
        `AffinityFunction`, `CacheConfiguration.getAffinity()`, `CacheConfiguration.setAffinity(AffinityFunction)`

    - #### backupPartitions

          int[] backupPartitions​(ClusterNode n)

      Gets partition ids for which given cluster node has backup ownership.
      Parameters:
        `n` - Cluster node.
      Returns:
        Partition ids for which given cluster node has backup ownership.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.
      See Also:
        `AffinityFunction`, `CacheConfiguration.getAffinity()`, `CacheConfiguration.setAffinity(AffinityFunction)`

    - #### allPartitions

          int[] allPartitions​(ClusterNode n)

      Gets partition ids for which given cluster node has any ownership (either primary or backup).
      Parameters:
        `n` - Cluster node.
      Returns:
        Partition ids for which given cluster node has any ownership, primary or backup.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.
      See Also:
        `AffinityFunction`, `CacheConfiguration.getAffinity()`, `CacheConfiguration.setAffinity(AffinityFunction)`

    - #### affinityKey

          Object affinityKey​(K key)

      Maps passed in key to a key which will be used for node affinity. The affinity key may be different from actual key if some field in the actual key was designated for affinity mapping via `AffinityKeyMapped` annotation or if a custom `AffinityKeyMapper` was configured.
      Parameters:
        `key` - Key to map.
      Returns:
        Key to be used for node-to-affinity mapping (may be the same key as passed in).
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.

    - #### mapKeysToNodes

          Map<ClusterNode,​Collection<K>> mapKeysToNodes​(Collection<? extends K> keys)

      This method provides ability to detect which keys are mapped to which nodes. Use it to determine which nodes are storing which keys prior to sending jobs that access these keys.

      This method works as following:

      - For local caches it returns only local node mapped to all keys.
      - For other caches, the returned map represents node-to-key affinity.
      Parameters:
        `keys` - Keys to map to nodes.
      Returns:
        Map of nodes to keys.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.

    - #### mapKeyToNode

          @Nullable
          @Nullable ClusterNode mapKeyToNode​(K key)

      This method provides ability to detect to which primary node the given key is mapped. Use it to determine which nodes are storing which keys prior to sending jobs that access these keys.

      This method works as following:

      - For local caches it returns only local node ID.
      - For other caches, primary node for the given key is returned.
      Parameters:
        `key` - Keys to map to a node.
      Returns:
        Primary node for the key.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.

    - #### mapKeyToPrimaryAndBackups

          Collection<ClusterNode> mapKeyToPrimaryAndBackups​(K key)

      Gets primary and backup nodes for the key. Note that primary node is always first in the returned collection.
      Parameters:
        `key` - Key to get affinity nodes for.
      Returns:
        Collection of primary and backup nodes for the key with primary node always first.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.

    - #### mapPartitionToNode

          ClusterNode mapPartitionToNode​(int part)

      Gets primary node for the given partition.
      Parameters:
        `part` - Partition id.
      Returns:
        Primary node for the given partition.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.
      See Also:
        `AffinityFunction`, `CacheConfiguration.getAffinity()`, `CacheConfiguration.setAffinity(AffinityFunction)`

    - #### mapPartitionsToNodes

          Map<Integer,​ClusterNode> mapPartitionsToNodes​(Collection<Integer> parts)

      Gets primary nodes for the given partitions.
      Parameters:
        `parts` - Partition ids.
      Returns:
        Mapping of given partitions to their primary nodes.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.
      See Also:
        `AffinityFunction`, `CacheConfiguration.getAffinity()`, `CacheConfiguration.setAffinity(AffinityFunction)`

    - #### mapPartitionToPrimaryAndBackups

          Collection<ClusterNode> mapPartitionToPrimaryAndBackups​(int part)

      Gets primary and backup nodes for partition. Note that primary node is always first in the returned collection.
      Parameters:
        `part` - Partition to get affinity nodes for.
      Returns:
        Collection of primary and backup nodes for partition with primary node always first.
      Throws:
        `IgniteException` - If there are no alive nodes for this cache.