Interface AffinityFunction
-
- All Superinterfaces:
Serializable
- All Known Implementing Classes:
PlatformDotNetAffinityFunction
,RendezvousAffinityFunction
public interface AffinityFunction extends Serializable
Cache key affinity which maps keys to nodes. This interface is utilized for both, replicated and partitioned caches. Cache affinity can be configured for individual caches viaCacheConfiguration.getAffinity()
method.Whenever a key is given to cache, it is first passed to a pluggable
AffinityKeyMapper
which may potentially map this key to an alternate key which should be used for affinity. The key returned fromAffinityKeyMapper.affinityKey(Object)
method is then passed topartition(Object)
method to find out the partition for the key. On each topology change, partition-to-node mapping is calculated usingassignPartitions(AffinityFunctionContext)
method, which assigns a collection of nodes to each partition. This collection of nodes is used for node affinity. InREPLICATED
cache mode the key will be cached on all returned nodes; generally, all caching nodes participate in caching every key in replicated mode. InPARTITIONED
mode, only primary and backup nodes are returned with primary node always in the first position. So if there is1
backup node, then the returned collection will have2
nodes in it -primary
node in first position, andbackup
node in second.For more information about cache affinity and examples refer to
AffinityKeyMapper
and@AffinityKeyMapped
documentation.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description List<List<ClusterNode>>
assignPartitions(AffinityFunctionContext affCtx)
Gets affinity nodes for a partition.int
partition(Object key)
Gets partition number for a given key starting from0
.int
partitions()
Gets total number of partitions available.void
removeNode(UUID nodeId)
Removes node from affinity.void
reset()
Resets cache affinity to its initial state.
-
-
-
Method Detail
-
reset
void reset()
Resets cache affinity to its initial state. This method will be called by the system any time the affinity has been sent to remote node where it has to be reinitialized. If your implementation of affinity function has no initialization logic, leave this method empty.
-
partitions
int partitions()
Gets total number of partitions available. All caches should always provide correct partition count which should be the same on all participating nodes. Note that partitions should always be numbered from0
inclusively toN
exclusively without any gaps.- Returns:
- Total partition count.
-
partition
int partition(Object key)
Gets partition number for a given key starting from0
. Partitioned caches should make sure that keys are about evenly distributed across all partitions from0
topartition count
for best performance.Note that for fully replicated caches it is possible to segment key sets among different grid node groups. In that case each node group should return a unique partition number. However, unlike partitioned cache, mappings of keys to nodes in replicated caches are constant and a node cannot migrate from one partition to another.
- Parameters:
key
- Key to get partition for.- Returns:
- Partition number for a given key.
-
assignPartitions
List<List<ClusterNode>> assignPartitions(AffinityFunctionContext affCtx)
Gets affinity nodes for a partition. In case of replicated cache, all returned nodes are updated in the same manner. In case of partitioned cache, the returned list should contain only the primary and back up nodes with primary node being always first.Note that partitioned affinity must obey the following contract: given that node
N
is primary for some keyK
, if any other node(s) leave grid and no node joins grid, nodeN
will remain primary for keyK
.- Parameters:
affCtx
- Affinity function context. Will provide all required information to calculate new partition assignments.- Returns:
- Unmodifiable list indexed by partition number. Each element of array is a collection in which first node is a primary node and other nodes are backup nodes.
-
removeNode
void removeNode(UUID nodeId)
Removes node from affinity. This method is called when it is safe to remove left node from affinity mapping.- Parameters:
nodeId
- ID of node to remove.
-
-