org.gridgain.grid.cache.affinity

Interface GridCacheAffinity<K>

All Known Implementing Classes:

GridCacheAffinityImpl, GridCacheAffinityProxy

public interface GridCacheAffinity<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 GridCache.affinity() method.

Mapping of a key to a node is a three-step operation. First step will get an affinity key for given key using GridCacheAffinityKeyMapper. If mapper is not specified, the original key will be used. Second step will map affinity key to partition using GridCacheAffinityFunction.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

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(GridNode n) Gets partition ids for which nodes of the given projection has ownership (either primary or backup).
int[]	backupPartitions(GridNode n) Gets partition ids for which nodes of the given projection has backup ownership.
boolean	isBackup(GridNode n, K key) Returns true if local node is one of the backup nodes for given key.
boolean	isPrimary(GridNode n, K key) Returns true if given node is the primary node for given key.
boolean	isPrimaryOrBackup(GridNode n, K key) Returns true if local node is primary or one of the backup nodes for given key.
Map<GridNode,Collection<K>>	mapKeysToNodes(Collection<? extends K> keys) This method provides ability to detect which keys are mapped to which nodes.
GridNode	mapKeyToNode(K key) This method provides ability to detect to which primary node the given key is mapped.
Collection<GridNode>	mapKeyToPrimaryAndBackups(K key) Gets primary and backup nodes for the key.
Map<Integer,GridNode>	mapPartitionsToNodes(Collection<Integer> parts) Gets primary nodes for the given partitions.
GridNode	mapPartitionToNode(int part) Gets primary node for the given partition.
Collection<GridNode>	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(GridNode n) Gets partition ids for which nodes of the given projection has primary ownership.

Method Detail

partitions

int partitions()

Gets number of partitions in cache according to configured affinity function.

Returns:

Number of cache partitions.

See Also:

GridCacheAffinityFunction, GridCacheConfiguration.getAffinity(), GridCacheConfiguration.setAffinity(GridCacheAffinityFunction)

partition

int partition(K key)

Gets partition id for the given key.

Parameters:

key - Key to get partition id for.

Returns:

Partition id.

See Also:

GridCacheAffinityFunction, GridCacheConfiguration.getAffinity(), GridCacheConfiguration.setAffinity(GridCacheAffinityFunction)

isPrimary

boolean isPrimary(GridNode n,
                K key)

Returns true if given node is the primary node for given key. To check if local node is primary for given key, pass Grid.localNode() as first parameter.

Parameters:

n - Node to check.

key - Key to check.

Returns:

True if local node is the primary node for given key.

isBackup

boolean isBackup(GridNode n,
               K key)

Returns true if local node is one of the backup nodes for given key. To check if local node is primary for given key, pass Grid.localNode() as first parameter.

Parameters:

n - Node to check.

key - Key to check.

Returns:

True if local node is one of the backup nodes for given key.

isPrimaryOrBackup

boolean isPrimaryOrBackup(GridNode n,
                        K key)

Returns true if local node is primary or one of the backup nodes for given key. To check if local node is primary or backup for given key, pass Grid.localNode() as first parameter.

This method is essentially equivalent to calling "isPrimary(GridNode, Object) || isBackup(GridNode, 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.

primaryPartitions

int[] primaryPartitions(GridNode n)

Gets partition ids for which nodes of the given projection has primary ownership.

Note that since GridNode implements GridProjection, to find out primary partitions for a single node just pass a single node into this method.

This method may return an empty array if none of nodes in the projection have nearOnly disabled.

Parameters:

n - Grid node.

Returns:

Partition ids for which given projection has primary ownership.

See Also:

GridCacheAffinityFunction, GridCacheConfiguration.getAffinity(), GridCacheConfiguration.setAffinity(GridCacheAffinityFunction)

backupPartitions

int[] backupPartitions(GridNode n)

Gets partition ids for which nodes of the given projection has backup ownership. Note that you can find a back up at a certain level, e.g. first backup or third backup by specifying the 'levels parameter. If no 'level' is specified then all backup partitions are returned.

Note that since GridNode implements GridProjection, to find out backup partitions for a single node, just pass that single node into this method.

This method may return an empty array if none of nodes in the projection have nearOnly disabled.

Parameters:

n - Grid node.

Returns:

Partition ids for which given projection has backup ownership.

See Also:

GridCacheAffinityFunction, GridCacheConfiguration.getAffinity(), GridCacheConfiguration.setAffinity(GridCacheAffinityFunction)

allPartitions

int[] allPartitions(GridNode n)

Gets partition ids for which nodes of the given projection has ownership (either primary or backup).

Note that since GridNode implements GridProjection, to find out all partitions for a single node, just pass that single node into this method.

This method may return an empty array if none of nodes in the projection have nearOnly disabled.

Parameters:

n - Grid node.

Returns:

Partition ids for which given projection has ownership.

See Also:

GridCacheAffinityFunction, GridCacheConfiguration.getAffinity(), GridCacheConfiguration.setAffinity(GridCacheAffinityFunction)

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 GridCacheAffinityKeyMapped annotation or if a custom GridCacheAffinityKeyMapper 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).

mapKeysToNodes

Map<GridNode,Collection<K>> mapKeysToNodes(@Nullable
                                         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 GridCacheAffinityFunction 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 or empty map if there are no alive nodes for this cache.

mapKeyToNode

@Nullable
GridNode 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 GridCacheAffinityFunction 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 or null if there are no alive nodes for this cache.

mapKeyToPrimaryAndBackups

Collection<GridNode> mapKeyToPrimaryAndBackups(K key)

Gets primary and backup nodes for the key. Note that primary node is always first in the returned collection.

If there are only cache nodes in the projection with GridCacheConfiguration.getDistributionMode() property set to NEAR_ONLY, then this method will return an empty collection.

Parameters:

key - Key to get affinity nodes for.

Returns:

Collection of primary and backup nodes for the key with primary node always first, or an empty collection if this projection contains only nodes with GridCacheConfiguration.getDistributionMode() property set to NEAR_ONLY.

mapPartitionToNode

GridNode mapPartitionToNode(int part)

Gets primary node for the given partition.

Parameters:

part - Partition id.

Returns:

Primary node for the given partition.

See Also:

GridCacheAffinityFunction, GridCacheConfiguration.getAffinity(), GridCacheConfiguration.setAffinity(GridCacheAffinityFunction)

mapPartitionsToNodes

Map<Integer,GridNode> mapPartitionsToNodes(Collection<Integer> parts)

Gets primary nodes for the given partitions.

Parameters:

parts - Partition ids.

Returns:

Mapping of given partitions to their primary nodes.

See Also:

GridCacheAffinityFunction, GridCacheConfiguration.getAffinity(), GridCacheConfiguration.setAffinity(GridCacheAffinityFunction)

mapPartitionToPrimaryAndBackups

Collection<GridNode> mapPartitionToPrimaryAndBackups(int part)

Gets primary and backup nodes for partition. Note that primary node is always first in the returned collection.

If there are only cache nodes in the projection with GridCacheConfiguration.getDistributionMode() property set to NEAR_ONLY, then this method will return an empty collection.

Parameters:

part - Partition to get affinity nodes for.

Returns:

Collection of primary and backup nodes for partition with primary node always first, or an empty collection if this projection contains only nodes with GridCacheConfiguration.getDistributionMode() property set to NEAR_ONLY.