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.
You can bind a SessionHandle object to a Session in the following ways:
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();
The following summarizes the routing behavior of major operation types in the per-container partition placement scenario with respect to SessionHandle objects.
In most cases, you should 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 will 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 will be 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.
programming example for the SessionHandle object 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, 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 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 will route to the partition specified by the SessionHandle. Without SessionHandle set, operations route to either all partitions or a randomly selected partition.