org.apache.ignite.cache.affinity

## Interface Affinity<K>

All Known Implementing Classes:
  GridCacheAffinityImpl, GridCacheAffinityProxy

    public interface Affinity<K>

Provides affinity information to detect which node is primary and which nodes are backups for a partitioned 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

Methods
`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 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.
`Map<ClusterNode,Collection<K>>` `mapKeysToNodes(Collection<? extends K> keys)` This method provides ability to detect which keys are mapped to which nodes.
`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 fully replicated caches `AffinityFunction` is used to determine which keys are mapped to which nodes.
- For partitioned 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
    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 fully replicated caches first node ID returned by `AffinityFunction` is returned.
- For partitioned 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.

2017 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 2.2.0
Release Date | : September 15 2017