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

Modifier and Type	Method and 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 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 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

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.

NullPointerException - if key is null.

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.