org.apache.ignite.cache.affinity

## Annotation Type AffinityKeyMapped

-     @Documented
       @Retention(value=RUNTIME)
       @Target(value=FIELD)
      public @interface AffinityKeyMapped

  Optional annotation to specify custom key-to-node affinity. Affinity key is a key which will be used to determine a node on which given cache key will be stored. This annotation allows to mark a field in the cache key object that will be used as an affinity key (instead of the entire cache key object that is used for affinity by default). Note that a class can have only one field annotated with `@AffinityKeyMapped` annotation.

  One of the major use cases for this annotation is the routing of grid computations to the nodes where the data for this computation is cached, the concept otherwise known as `Collocation Of Computations And Data`.

  # Mapping Cache Keys

  The default implementation of `AffinityKeyMapper`, which will be used if no explicit affinity mapper is specified in cache configuration, will first look for any field annotated with `@AffinityKeyMapped` annotation. If such field is not found, then the cache key itself will be used for key-to-node affinity (this means that all objects with the same cache key will always be routed to the same node). If such field is found, then the value of this field will be used for key-to-node affinity. This allows to specify alternate affinity key, other than the cache key itself, whenever needed.

  For example, if a `Person` object is always accessed together with a `Company` object for which this person is an employee, then for better performance and scalability it makes sense to collocate `Person` objects together with their `Company` object when storing them in cache. To achieve that, cache key used to cache `Person` objects should have a field or method annotated with `@AffinityKeyMapped` annotation, which will provide the value of the company key for which that person works, like so:

       public class PersonKey {
           // Person ID used to identify a person.
           private String personId;

           // Company ID which will be used for affinity.
           @AffinityKeyMapped
           private String companyId;
           ...
       }
       ...
       // Instantiate person keys.
       Object personKey1 = new PersonKey("myPersonId1", "myCompanyId");
       Object personKey2 = new PersonKey("myPersonId2", "myCompanyId");

       // Both, the company and the person objects will be cached on the same node.
       cache.put("myCompanyId", new Company(..));
       cache.put(personKey1, new Person(..));
       cache.put(personKey2, new Person(..));

  ## AffinityKey

  For convenience, you can also optionally use `AffinityKey` class. Here is how a `PersonKey` defined above would look using `AffinityKey`:

       Object personKey1 = new AffinityKey("myPersonId1", "myCompanyId");
       Object personKey2 = new AffinityKey("myPersonId2", "myCompanyId");

       // Both, the company and the person objects will be cached on the same node.
       cache.put(myCompanyId, new Company(..));
       cache.put(personKey1, new Person(..));
       cache.put(personKey2, new Person(..));

  # Collocating Computations And Data

  It is also possible to route computations to the nodes where the data is cached. This concept is otherwise known as `Collocation Of Computations And Data`. In this case, `@AffinityKeyMapped` annotation allows to specify a routing affinity key for a `ComputeJob` or any other grid computation, such as `Runnable`, `Callable`, or `IgniteClosure`. It should be attached to a field that provides affinity key for the computation. Only one annotation per class is allowed. Whenever such annotation is detected, then `LoadBalancingSpi` will be bypassed, and computation will be routed to the grid node where the specified affinity key is cached.

  For more information about cache affinity also see `AffinityKeyMapper` and `AffinityFunction` documentation. Affinity for a key can be found from any node, regardless of whether it has cache started or not. If cache is not started, affinity function will be fetched from the remote node which does have the cache running.

  See Also:
    `AffinityFunction`, `AffinityKeyMapper`, `AffinityKey`

${current.year} Copyright © Apache Software Foundation
| Follow @ApacheIgnite
Ignite Database and Caching Platform | : ver. 2.16.0
Release Date | : December 15 2023