Integração do SessionHandle

Um objeto SessionHandle inclui informações de partição para o Session ao qual ele está ligado e facilita o roteamento da solicitação. Os objetos SessionHandle se aplicam apenas no cenário de posicionamento de partição por contêiner.

Objeto SessionHandle para Roteamento de Solicitação

É possível ligar um objeto SessionHandle a um Session das seguintes formas:

Dica: Em cada uma das chamadas de método a seguir, depois de um objeto SessionHandle ser ligado a um Session, o objeto SessionHandle poderá ser obtido a partir do método Session.getSessionHandle.
  • Chame o método Session.getSessionHandle: Quando este método é chamado, se nenhum objeto SessionHandle estiver ligado ao Session, um objeto SessionHandle será selecionado aleatoriamente e ligado ao Session.
  • Chame as operações transacionais de criação, leitura, atualização e de exclusão: Quando esses métodos são chamados no tempo de confirmação, se nenhum objeto SessionHandle estiver ligado ao Session, um objeto SessionHandle será selecionado aleatoriamente e ligado ao Session.
  • Chame o método ObjectMap.getNextKey: Quando esse método é chamado, se nenhum objeto SessionHandle estiver ligado ao Session, a solicitação da operação será roteada aleatoriamente para partições individuais até a chave ser obtida. Se uma chave for retornada de uma partição, um objeto SessionHandle correspondente a essa partição será ligado ao Session. Se nenhuma chave for localizada, nenhum SessionHandle será ligado ao Session.
  • Chame os métodos QueryQueue.getNextEntity ou QueryQueue.getNextEntities: Quando esse método é chamado, se nenhum objeto SessionHandle estiver ligado ao Session, a solicitação da operação será roteada aleatoriamente para partições individuais até um objeto ser obtido. Se um objeto for retornado de uma partição, um objeto SessionHandle correspondente a essa partição será ligado ao Session. Se nenhum objeto for localizado, nenhum SessionHandle será ligado ao Session.
  • Configure um SessionHandle com o método Session.setSessionHandle(SessionHandle sh): Se SessionHandle for obtido a partir do método Session.getSessionHandle, o SessionHandle poderá ser ligado a um Session. A configuração de um SessionHandle influencia o roteamento de solicitações dentro do escopo do Session ao qual ele está ligado.

O método Session.getSessionHandle sempre retorna um objeto SessionHandle. O método também ligará automaticamente um SessionHandle no Session se nenhum objeto SessionHandle estiver ligado ao Session. Se desejar verificar se um Session tem apenas um objeto SessionHandle, chame o método Session.isSessionHandleSet. Se esse método retornar um valor false, nenhum SessionHandle estará ligado atualmente ao Session.

Principais Tipos de Operações no Cenário de Posicionamento por Contêiner

A seguir há um resumo do comportamento de roteamento dos principais tipos de operações no cenário de posicionamento de partição por contêiner em relação aos objetos SessionHandle.

  • Objeto Session com o objeto SessionHandle ligado
    • Índice - API de MapIndex e MapRangeIndex: SessionHandle
    • Query e ObjectQuery: SessionHandle
    • Agente - API de MapGridAgent e ReduceGridAgent API: SessionHandle
    • ObjectMap.Clear: SessionHandle
    • ObjectMap.getNextKey: SessionHandle
    • QueryQueue.getNextEntity, QueryQueue.getNextEntities: SessionHandle
    • Operações transacionais de criação, recuperação, atualização e exclusão (API de ObjectMap e API de EntityManager): SessionHandle
  • Objeto Session sem o objeto SessionHandle ligado
    • Índice - API de MapIndex e MapRangeIndex: Todas as partições ativas atuais
    • Query e ObjectQuery: Partição especificada com o método setPartition de Query e ObjectQuery
    • Agente - MapGridAgent e ReduceGridAgent
      • Não suportado: método ReduceGridAgent.reduce(Session s, ObjectMap map, Collection keys) e MapGridAgent.process(Session s, ObjectMap map, Object key).
      • Todas as partições ativas atuais: método ReduceGridAgent.reduce(Session s, ObjectMap map) e MapGridAgent.processAllEntries(Session s, ObjectMap map).
    • ObjectMap.clear: Todas as partições ativas atuais.
    • ObjectMap.getNextKey: Liga um SessionHandle ao Session se uma chave for retornada de uma das partições selecionadas aleatoriamente. Se nenhuma chave for retornada, o Session não será ligado a nenhum SessionHandle.
    • QueryQueue: Especifica uma partição com o método QueryQueue.setPartition. Se nenhuma partição for configurada, o método seleciona aleatoriamente uma partição para retornar. Se um objeto for retornado, o Session atual será ligado com o SessionHandle que é ligado à partição que retorna o objeto. Se nenhum objeto for retornado, o Session não será ligado a nenhum SessionHandle.
    • Operações transacionais de criação, recuperação, atualização e exclusão (API de ObjectMap e API de EntityManager): Selecione uma partição aleatoriamente.

    Na maioria dos casos, use SessionHandle para controlar o roteamento para uma determinada partição. É possível recuperar e armazenar em cache o SessionHandle a partir do Session que insere dados. Depois de armazenar em cache o SessionHandle, é possível configurá-lo em outro Session para que você possa rotear solicitações para a partição especificada pelo SessionHandle em cache. Para executar operações como ObjectMap.clear sem o SessionHandle, é possível configurar temporariamente o SessionHandle como nulo ao chamar Session.setSessionHandle(null). Sem um SessionHandle especificado, as operações são executadas em todas as partições ativas atuais.

  • Comportamento de roteamento de QueryQueue

    No cenário de posicionamento de partição por contêiner, o SessionHandle pode ser usado para controlar o roteamento dos métodos getNextEntity e getNextEntities da API de QueryQueue. Se o Session estiver ligado a um SessionHandle, as solicitações são roteadas para a partição à qual o SessionHandle está ligado. Se o Session não estiver ligado a um SessionHandle, as solicitações serão roteadas para a partição configurada com o método QueryQueue.setPartition se uma partição tiver sido configurada dessa forma. Se o Session não tiver ligado SessionHandle ou à partição, uma partição selecionada aleatoriamente será retornada. Se nenhuma partição for localizada, o processo será interrompido e nenhum SessionHandle será ligado ao Session atual.

O fragmento de código a seguir mostra como usar os objetos SessionHandle.

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

Considerações de Design do Aplicativo

No cenário de estratégia de posicionamento por contêiner, use o objeto SessionHandle para a maioria das operações. O objeto SessionHandle controla o roteamento para as partições. Para recuperar dados, o objeto SessionHandle que é ligado ao Session deverá ser o mesmo objeto SessionHandle de qualquer transação de inserção de dados.

Quando desejar executar uma operação sem um SessionHandle configurado no Session, é possível desvincular um SessionHandle de um Session ao chamar o método Session.setSessionHandle(null).

Quando um Session for ligado a um SessionHandle, todas as solicitações de operação serão roteadas para a partição especificada pelo objeto SessionHandle. Sem o objeto SessionHandle configurado, as operações serão roteadas para todas as partições ou para uma partição selecionada aleatoriamente.