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 Detail

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

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

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