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.

• Invoke the Session.getSessionHandle method: At the time this method is invoked, if there is no SessionHandle bound to the Session, a SessionHandle will be selected randomly and bound to the Session.

• Invoke transactional create, read, update, delete (CRUD) operations: At the time these methods are invoked or at commit time, if there is no SessionHandle bound to the Session, a SessionHandle will be selected randomly and bound to the Session.

• Invoke ObjectMap.getNextKey method: At the time this method is invoked, if there is no SessionHandle bound to the Session, the operation request will be randomly routed to individual partitions until a key is obtained. If a key is returned from a partition, a SessionHandle corresponding to that partition will be bound to the Session. If no key is found, no SessionHandle will be bound to the Session.

• Invoke QueryQueue.getNextEntity or QueryQueue.getNextEntities method: At the time this method is invoked, if there is no SessionHandle bound to the Session, the operation request will be randomly routed to individual partitions until an object is obtained. If an object is returned from a partition, a SessionHandle corresponding to that partition will be bound to the Session. If no object is found, no SessionHandle will be 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 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.

• 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 CRUD 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 via 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 will randomly select 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 CRUD operations (ObjectMap API and EntityManager API): Randomly select a partition.

  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.

• 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 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.

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

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

+

Search Tips   |   Advanced Search