Program guide > Access data with client applications > Use Sessions to access data in the grid

SessionHandle integration

A SessionHandle object includes the partition information for the Session to which it is bound and facilitates request routing. SessionHandle objects only apply to the per-container partition placement scenario.

SessionHandle object for request routing

You can bind a SessionHandle object to a Session in the following ways:

Tip: In each of the following method calls, once a SessionHandle is bound to a Session, the SessionHandle can be obtained from the Session.getSessionHandle method which is used with the Session.setSessionHandle method.

The Session.getSessionHandle method will always return a SessionHandle and automatically bind a SessionHandle on the Session if there is no SessionHandle bound to the Session. If you only want to verify whether a Session has a SessionHandle, call the Session.isSessionHandleSet method. If this method returns a value of false, no SessionHandle is currently bound to the Session.

new method added to Session API
     * Determines if a SessionHandle is currently set on this Session.
     * @return true if a SessionHandle is currently set on this session.
     * @since 7.1

    public boolean isSessionHandleSet();

Major operation types in the per-container placement scenario

The following summarizes the routing behavior of major operation types in the per-container partition placement scenario with respect to SessionHandle objects.

The following snippet of code shows how to use SessionHandle.

Program example for the SessionHandle object

Session ogSession = objectGrid.getSession();

// binding the SessionHandle
SessionHandle sessionHandle = ogSession.getSessionHandle();

ObjectMap map = ogSession.getMap("planet");
map.insert("planet1", "mercury");

// transaction is routed to partition specified by SessionHandle

// cache the SessionHandle that inserts data
SessionHandle cachedSessionHandle = ogSession.getSessionHandle();

// verify if SessionHandle is set on the Session
boolean isSessionHandleSet = ogSession.isSessionHandleSet();

// temporarily unbind the SessionHandle from the Session
if(isSessionHandleSet) {

// if the Session has no SessionHandle bound, 
// the clear operation will run on all current active partitions
// and thus remove all data from the map in the entire grid

// after clear is done, reset the SessionHandle back, 
// if the Session needs to use previous SessionHandle.
// Optionally, calling getSessionHandle can get a new SessionHandle

Application design considerations

In the per-container placement strategy scenario, you should use SessionHandle for most operations. The SessionHandle controls routing to partitions. To retrieve data, the SessionHandle you bind to the Session should be same SessionHandle from any insert data transaction.

When to perform an operation without a SessionHandle set on the Session, you can unbind a SessionHandle from a Session by making a Session.setSessionHandle(null) method call.

When a Session is bound to a SessionHandle, all operation requests will route to the partition specified by the SessionHandle. Without SessionHandle set, operations route to either all partitions or a randomly selected partition.

Parent topic:

Use Sessions to access data in the grid

Related concepts

SessionHandle for routing