Package com.hazelcast.partition

Interface PartitionAware<T>

Type Parameters:
T - key type
All Known Implementing Classes:
PartitionAwareKey
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface PartitionAware<T>
PartitionAware means that data will be based in the same member based on the partition key and implementing tasks will be executed on the getPartitionKey()'s owner member.

This achieves data affinity. Data and execution occurs on the same partition.

In Hazelcast, disparate data structures will be stored on the same partition, based on the partition key. For example, if "Steve" was used, then the following would be on one partition.

  • a customers IMap with an entry of key "Steve"
  • an orders IMap using a customer key type implementing PartitionAware with key "Steve"
  • any queue named "Steve"
  • any PartitionAware object with partition key "Steve"
If you have a IExecutorService which needs to deal with a customer and a customer's orders, you can achieve optimal performance by putting them on the same partition.

DistributedObject also has a notion of the partition key which is of type String to ensure that the same partition as distributed Objects Strings is used for the partition key.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    T
    getPartitionKey()
    The key that will be used by Hazelcast to specify the partition.

  • Method Details

    • getPartitionKey

      T getPartitionKey()
      The key that will be used by Hazelcast to specify the partition. You should give the same key for objects that you want to be in the same partition.

      The contract of getPartitionKey() method is as follows:

      Let us define toData(o) as serialized form of given object obtained by using Hazelcast Serialization configured for the cluster (the exact method used is SerializationService.toData from an internal SPI).

      Assume PartitionAware a, b are objects (e.g. IMap keys) and T pk1 = a.getPartitionKey(), pk2 = b.getPartitionKey() are partition key values.

      Then getPartitionKey() implementation must obey the following contract:

      1. (mandatory) Deterministic partitioning: if a.equals(b) then either toData(a.getPartitionKey()).equals(toData(b.getPartitionKey())) or a.getPartitionKey() == null && b.getPartitionKey() == null
      2. (recommended) Reasonable partitioning: if a.equals(b) then a.getPartitionKey().equals(b.getPartitionKey())
      3. (recommended) Reasonable partitioning key serialization (if custom serialization is used): if pk1.equals(pk2) then toData(pk1).equals(toData(pk2))
      4. The above stated conditions must hold when the getPartitionKey() is invoked any number of times on any member or client, regardless of time (note that some partitioned data structures support persistence) and if the JVM is restarted, regardless of client/member version and JVM version (across all JVMs ever used in given deployment), timezone, locale and similar differences in the environment.
      Adhering to the contract guarantees stable partitioning of the data and ability to find appropriate member and partition who owns given object during querying and modifications.

      Notes:

      • getPartitionKey() contract is similar to hashCode() but with stricter long-term requirements.
      • Partition key is not compared directly, only serialized form is compared or used to calculate partition id.
      • For unequal objects getPartitionKey() may return the same or different values according to specific partitioning use case needs.
      Returns:
      the key that specifies the partition. Returning null or this will cause the result as if the object did not implement PartitionAware. If the returned key itself implements PartitionAware, this fact will be ignored and the key will be treated as a plain object.