10.2. Grouping API

The grouping API allows a group of entries to be co-located on the same node, instead of the default behavior of having each entry being stored on a node corresponding to a calculated hash code of the entry. By default JBoss Data Grid will take a hash code of each key when it is stored and map that key to a hash segment; this allows an algorithm to be used to determine the node that contains the key, allowing each node in the cluster to know which node contains the key without distributing ownership information. This behavior reduces overhead and improves redundancy as the ownership information does not need to be replicated should a node fail.

By enabling the grouping API the hash of the key is ignored when deciding which node to store the entry on. Instead, a hash of the group is obtained and used in its place, while the hash of the key is used internally to prevent performance degradation. When the group API is in use every node can still determine the owners of the key, and due to this reason the group may not be manually specified. A group may either be intrinsic to the entry, generated by the key class, or extrinsic to the entry, generated by an external function.

The grouping API may be enabled on a per-cache basis by adding the groups element as seen in the following example:

<distributed-cache>
    <groups enabled="true"/>
</distributed-cache>

Assuming a custom Grouper exists it may be defined by passing in the classname as seen below:

<distributed-cache>
    <groups enabled="true">
        <grouper class="com.acme.KXGrouper" />
    </groups>
</distributed-cache>