This filter is intended to be used to optimize queries for partitioned caches that utilize any of the key association algorithms (by implementing either KeyAssociator or KeyAssociation) to ensure placement of all associated entries in the same distributed cache partition (and therefore in the same storage-enabled cluster node). Using the KeyAssociatedFilter will instruct the distributed cache to apply the wrapped filter only to the entries stored at the cache service node that owns the specified host key.

Note 1: This filter must be the outermost filter and cannot be used as a part of any composite filter (AndFilter, OrFilter, etc.)

Note 2: This filter is intended to be processed only on the client side of the partitioned cache service.

For example, consider two classes called Parent and Child that are stored in separate caches using ParentKey and ChildKey objects respectively. The Parent and Child classes have a Id property that returns a Long value that uniquely identifies the object. Similarly, the ParentKey and ChildKey classes have a Id property that uniquely identifies the corresponding cached object. Futhermore, the Child and ChildKey classes include a ParentId property that returns the Long identifier of the Parent object.

There are two ways to ensure that Child objects are collocated with their Parent objects (in the same storage-enabled cluster node).

1. Make the ChildKey class implement KeyAssociation as follows:
   CopyC#

   public Object AssociatedKey
   {
       get { return ParentId; }
   }

   and the ParentKey class implement KeyAssociation as follows:
   CopyC#

   public Object AssociatedKey
   {
       get { return Id; }
   }

2. Implement a custom KeyAssociator as follows:
   CopyC#

   public object GetAssociatedKey(object key)
   {
       if (key is ChildKey)
       {
           return ((ChildKey) key).ParentId;
       }
       else if (key is ParentKey)
       {
           return ((ParentKey) key).Id;
       }
       else
       {
       return null;
       }
   }

Now, to retrieve all the Child objects of a given Parent using an optimized query you would do the following:

CopyC#

ParentKey parentKey = new ParentKey(...);
Long      parentId  = parentKey.Id;

// this Filter will be applied to all Child objects in order to fetch
// those for which ParentId returns the specified Parent identifier
IFilter filterEq = new EqualsFilter("ParentId", parentId);

// this Filter will direct the query to the cluster node that
// currently owns the Parent object with the given identifier
IFilter filterAsc = new KeyAssociatedFilter(filterEq, parentId);

// run the optimized query to get the ChildKey objects
ICollection colChildKeys = cacheChildren.Keys(filterAsc);

// get all the Child objects at once
ICollection colChildren = cacheChildren.GetAll(colChildKeys);

CopyC#

cacheChildren.Keys.RemoveAll(colChildKeys);