Chapter 5. The Grouping API

Use the following steps to configure the Grouping API:

The first step to set up the Grouping API is to enable groups. The following example demonstrates how to enable Groups:

Configuration c = new ConfigurationBuilder().clustering().hash().groups().enabled().build();

Use an intrinsic group with the Grouping API if:

Use the @Group annotation in the relevant method to specify an intrinsic group. The group must always be a String, as illustrated in the example:

class User {

   <!-- Additional configuration information here -->
   String office;
   <!-- Additional configuration information here -->

   public int hashCode() {
      // Defines the hash for the key, normally used to determine location
      <!-- Additional configuration information here -->
   }

   // Override the location by specifying a group, all keys in the same
   // group end up with the same owner
   @Group
   String getOffice() {
      return office;
   }

}

Specify an extrinsic group for the Grouping API if:

An extrinsic group is specified using an implementation of the Grouper interface. This interface uses the computeGroup method to return the group.

In the process of specifying an extrinsic group, the Grouper interface acts as an interceptor by passing the computed value to computeGroup. If the @Group annotation is used, the group using it is passed to the first Grouper. As a result, using an intrinsic group provides even greater control.

public class KXGrouper implements Grouper<String> {

   // A pattern that can extract from a "kX" (e.g. k1, k2) style key
   // The pattern requires a String key, of length 2, where the first character is
   // "k" and the second character is a digit. We take that digit, and perform
   // modular arithmetic on it to assign it to group "1" or group "2".

   private static Pattern kPattern = Pattern.compile("(^k)(\\d)$");

    public String computeGroup(String key, String group) {
        Matcher matcher = kPattern.matcher(key);
        if (matcher.matches()) {
            String g = Integer.parseInt(matcher.group(2)) % 2 + "";
            return g;
        } else
            return null;
    }

    public Class<String> getKeyType() {
        return String.class;
    }

}

After creation, each grouper must be registered to be used.

Configuration c = new ConfigurationBuilder().clustering().hash().groups().addGrouper(new KXGrouper()).enabled().build();