A SessionHandle object includes the partition information for the Session to which it is bound and facilitates request routing. SessionHandle objects apply to the per-container partition placement scenario only.
You can bind a SessionHandle object to a Session in the following ways:
The Session.getSessionHandle method always returns a SessionHandle object. The method also automatically binds a SessionHandle on the Session if no SessionHandle object is bound to the Session. If you want to verify whether a Session has a SessionHandle object only , call the Session.isSessionHandleSet method. If this method returns a value of false, no SessionHandle object is currently bound to the Session.
A summary of the routing behavior of major operation types in the per-container partition placement scenario with respect to SessionHandle objects follows.
In most cases, use SessionHandle to control routing to a particular partition. You can retrieve and cache the SessionHandle from the Session that inserts data. After caching the SessionHandle, you can set it on another Session so that you can route requests to the partition specified by the cached SessionHandle. To perform operations such as ObjectMap.clear without SessionHandle, you can temporarily set the SessionHandle to null by calling Session.setSessionHandle(null). Without a specified SessionHandle, operations run on all current active partitions.
In the per-container partition placement scenario, you can use SessionHandle to control routing of getNextEntity and getNextEntities methods of the QueryQueue API. If the Session is bound to a SessionHandle, requests route to the partition to which the SessionHandle is bound. If the Session is not bound to a SessionHandle, requests are routed to the partition set with the QueryQueue.setPartition method if a partition has been set in this way. If the Session has no bound SessionHandle or partition, a randomly selected partition are returned. If no such partition is found, the process stops and no SessionHandle is bound to the current Session.
The following snippet of code shows how to use SessionHandle objects.
Session ogSession = objectGrid.getSession();
// binding the SessionHandle
SessionHandle sessionHandle = ogSession.getSessionHandle();
ogSession.begin();
ObjectMap map = ogSession.getMap("planet");
map.insert("planet1", "mercury");
// transaction is routed to partition specified by SessionHandle
ogSession.commit();
// 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) {
ogSession.setSessionHandle(null);
}
// 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
map.clear();
// after clear is done, reset the SessionHandle back,
// if the Session needs to use previous SessionHandle.
// Optionally, calling getSessionHandle can get a new SessionHandle
ogSession.setSessionHandle(cachedSessionHandle);
In the per-container placement strategy scenario, use the SessionHandle object for most operations. The SessionHandle object controls routing to partitions. To retrieve data, the SessionHandle object that you bind to the Session must be same SessionHandle object from any insert data transaction.
When you want 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 route to the partition that is specified by the SessionHandle object. Without the SessionHandle object set, operations route to either all partitions or a randomly selected partition.