[Java programming language only]

SessionHandle integration

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.

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, after a SessionHandle object is bound to a Session, the SessionHandle object can be obtained from the Session.getSessionHandle method.
  • Call the Session.getSessionHandle method: When this method is called, if no SessionHandle object is bound to the Session, a SessionHandle object is selected randomly and bound to the Session.
  • Call transactional create, read, update, delete operations: When these methods are called or at commit time, if no SessionHandle object is bound to the Session, a SessionHandle object is selected randomly and bound to the Session.
  • Call ObjectMap.getNextKey method: When this method is called, if no SessionHandle object is bound to the Session, the operation request is randomly routed to individual partitions until a key is obtained. If a key is returned from a partition, a SessionHandle object that corresponds to that partition is bound to the Session. If no key is found, no SessionHandle is bound to the Session.
  • Call the QueryQueue.getNextEntity or QueryQueue.getNextEntities methods: At the time this method is called, if no SessionHandle object is bound to the Session, the operation request is randomly routed to individual partitions until an object is obtained. If an object is returned from a partition, a SessionHandle object that corresponds to that partition is bound to the Session. If no object is found, no SessionHandle is bound to the Session.
  • Set a SessionHandle with the Session.setSessionHandle(SessionHandle sh) method: If a SessionHandle is obtained from the Session.getSessionHandle method, the SessionHandle can be bound to a Session. Setting a SessionHandle influences request routing within the scope of the Session to which it is bound.

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.

Major operation types in the per-container placement scenario

A summary of the routing behavior of major operation types in the per-container partition placement scenario with respect to SessionHandle objects follows.

  • Session object with bound SessionHandle object
    • Index - MapIndex and MapRangeIndex API: SessionHandle
    • Query and ObjectQuery: SessionHandle
    • Agent - MapGridAgent and ReduceGridAgent API: SessionHandle
    • ObjectMap.Clear: SessionHandle
    • ObjectMap.getNextKey: SessionHandle
    • QueryQueue.getNextEntity, QueryQueue.getNextEntities: SessionHandle
    • Transactional create, retrieve, update, and delete operations (ObjectMap API and EntityManager API): SessionHandle
  • Session object without bound SessionHandle object
    • Index - MapIndex and MapRangeIndex API: All current active partitions
    • Query and ObjectQuery: Specified partition with setPartition method of Query and ObjectQuery
    • Agent - MapGridAgent and ReduceGridAgent
      • Not supported: ReduceGridAgent.reduce(Session s, ObjectMap map, Collection keys) and MapGridAgent.process(Session s, ObjectMap map, Object key) method.
      • All current active partitions: ReduceGridAgent.reduce(Session s, ObjectMap map) and MapGridAgent.processAllEntries(Session s, ObjectMap map) method.
    • ObjectMap.clear: All current active partitions.
    • ObjectMap.getNextKey: Binds a SessionHandle to the Session if a key is returned from one of the randomly selected partitions. If no key is returned, the Session is not bound to a SessionHandle.
    • QueryQueue: Specifies a partition with the QueryQueue.setPartition method. If no partition is set, the method randomly selects a partition to return. If an object is returned, the current Session is bound with the SessionHandle that is bound to the partition that returns the object. If no object is returned, the Session is not bound to a SessionHandle.
    • Transactional create, retrieve, update, and delete operations (ObjectMap API and EntityManager API): Randomly select a partition.

    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.

  • QueryQueue routing behavior

    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);

Application design considerations

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.