SessionHandle for routing

When you are using a per-container partition placement policy, you can use a SessionHandle object. A SessionHandle object contains partition information for the current Session and can be reused for a new Session.

A SessionHandle object includes information for the partition to which the current Session is bound. SessionHandle is extremely useful for the per-container partition placement policy and can be serialized with standard Java™ serialization.

If you have a SessionHandle object, you can apply that handle to a Session with the setSessionHandle(SessionHandle target) method, passing the handle in as the target. You can retrieve the SessionHandle object with the Session.getSessionHandle method.

Because it is only applicable in a per-container placement scenario, getting the SessionHandle object throws an IllegalStateException if a given data grid has multiple per-container map sets or has no per-container map sets. If you do not invoke the setSessionHandle method before calling the getSessionHandle method, the appropriate SessionHandle object is selected based on your client properties configuration.

You can also use the SessionHandleTransformer helper class to convert the handle into different formats. The methods of this class can change a handle's representation from byte array to instance, string to instance, and vice versa for both cases, and can also write the handle's contents into the output stream.

For an example on how you can use a SessionHandle object, see Zone-preferred routing.