Usar organização e cache da sessão

Nota

Ainda não tem um cache de avaliação? Essa unidade exige uma avaliação do cache da plataforma ativa. Solicita uma avaliação usando as instruções da unidade anterior. Se você não tem um cache de avaliação, ainda pode seguir as etapas desta unidade, mas seus dados não serão encontrados no cache.

Para usar o cache da plataforma, configure pelo menos uma partição. Depois de configurar as partições, você poderá adicionar, acessar e remover dados delas usando a API do Apex de cache da plataforma.

Cada partição tem um segmento de cache da sessão e um de cache da organização. Você pode alocar capacidades diferentes para cada segmento. Normalmente são alocados pelo menos 5 MB para sua partição. Para este exemplo, não estamos alocando nenhum espaço para fazer com que seu código lide com falhas de cache corretamente. Quando nenhum espaço é alocado, a taxa de falhas de cache é de 100%, o que significa que os valores de cache não são encontrados nele e o método get() retorna null. Pense nessa técnica para testar falhas de cache. Abordaremos o tratamento de falhas de cache em uma próxima seção.

Para começar, vamos criar uma partição na página Cache da plataforma (disponível apenas no Salesforce Classic).

1. Em Configuração, insira Cache da plataforma na caixa Busca rápida e selecione Cache da plataforma.
2. Clique em Nova partição de cache da plataforma.
3. Dê um nome à partição (por exemplo, o nome do aplicativo).
4. Marque a opção Partição padrão.
5. Digite 0 para cache da sessão e 0 para cache da organização e clique em Salvar. 

Cada chave de cache tem o seguinte formato:

Namespace.Partition.Key

Namespace é o nome do namespace da organização em que o aplicativo está sendo executado, que também pode ser definido com o incrível nome de “local”. O nome “local” se refere ao namespace de sua organização, independentemente de haver um namespace definido na organização ou não.

Partition é o nome da partição que você criou. Neste exemplo é CurrencyCache.

Key é o nome da chave usada para armazenar um valor. O nome da chave representa o valor em cache de forma exclusiva.

Digamos que você gostaria de armazenar a taxa de câmbio de dólar americano para euro. Podemos criar uma chave chamada DollarToEuroRate. Para a partição que acabamos de criar, o nome completo da chave é:

local.CurrencyCache.DollarToEuroRate

Por exemplo, este trecho de código armazena um valor no cache da organização para a chave DollarToEuroRate.

Cache.Org.put('local.CurrencyCache.DollarToEuroRate', '0.91');

A partição criada é uma partição padrão e, por isso, você pode omitir o namespace e o nome da partição e especificar apenas o nome da chave.

DollarToEuroRate

Ao usar uma partição padrão, você pode abreviar a chamada put() para o seguinte.

Cache.Org.put('DollarToEuroRate', '0.91');

Você acabou de configurar partições, que é a única etapa realizada na interface de usuário. Agora vamos mudar para Apex a fim de gerenciar o cache. Use o cache da organização para armazenar dados disponíveis para todos na organização. Use os métodos da classe Cache.Org ou a classe Cache.OrgPartition para referenciar determinada partição. Em seguida, chame os métodos de cache nessa partição.

O trecho de código do Apex a seguir mostra como acessar uma partição usando a classe Cache.OrgPartition para armazenar e recuperar um valor de cache de um aplicativo de câmbio de moedas. Ele obtém a partição chamada CurrencyCache no namespace local. Um novo valor é adicionado com a chave DollarToEuroRate e a taxa de câmbio da moeda no dia. Em seguida, o valor da chave DollarToEuroRate é recuperado do cache.

// Get partition
Cache.OrgPartition orgPart = Cache.Org.getPartition('local.CurrencyCache');
// Add cache value to the partition. Usually, the value is obtained from a 
// callout, but hardcoding it in this example for simplicity.
orgPart.put('DollarToEuroRate', '0.91');
// Retrieve cache value from the partition
String cachedRate = (String)orgPart.get('DollarToEuroRate');

Se você está administrando valores de cache em apenas uma partição, use os métodos de Cache.OrgPartition. Os métodos de Cache.OrgPartition são mais fáceis de usar que os métodos de Cache.Org porque você especifica o namespace e o prefixo da partição somente uma vez, na hora de criar o objeto de partição.

O exemplo anterior assume que tudo funciona corretamente, especialmente que:

• O cache da plataforma está ativo e tem uma partição com espaço disponível
• O valor de cache foi encontrado no cache
• O valor foi armazenado no cache com êxito

Mas, na vida real, os dados em cache nem sempre são garantidos. O cache da plataforma serve como espaço temporário. Por exemplo, o cache pode ter expirado. Mesmo que o cache ainda esteja lá, é possível que os dados em cache sejam removidos dele. Assim como os esquilos esvaziam suas bochechas para dar espaço a outras nozes, o cache da plataforma também se esvazia para receber mais dados! Quando o limite da partição é excedido, o Salesforce remove os dados em cache com base em um algoritmo “usado menos recentemente” (LRU, least recently used). A remoção do cache ocorre até que o uso seja reduzido a 100% da capacidade ou menos. Além disso, se você ultrapassar o limite de cache local, os itens poderão ser removidos do cache local antes de haver a confirmação da solicitação.

Como uma melhor prática, seu código deve antecipar e acomodar pontos de falha. Em outras palavras, assuma sempre a possibilidade de ocorrer uma falha de cache. Falha de cache ocorre quando você solicita um valor de uma chave ao cache, mas o valor não é encontrado. O valor retornado pela chamada get() é null. Confira o resultado da chamada get() como null e lide com ele como for necessário. Por exemplo, se o resultado é null, obtenha o valor do banco de dados ou de uma chamada de API.

O trecho de código do Apex a seguir mostra como lidar com uma falha de cache verificando se o valor retornado do cache não é null (if (cachedRate != null)). Se o valor não for null, você poderá usá-lo para exibição em uma página, por exemplo. Do contrário, busque esse valor em outra fonte, como uma chamada de API ou do Salesforce.

Cache.OrgPartition orgPart = Cache.Org.getPartition('local.CurrencyCache');
String cachedRate = (String)orgPart.get('DollarToEuroRate');
// Check the cache value that the get() call returned.
if (cachedRate != null) {
    // Display this exchange rate   
} else {
    // We have a cache miss, so fetch the value from the source.
    // Call an API to get the exchange rate.
}

Lembra o que o cache da sessão faz? É isso aí, ele armazena dados vinculados a sessões de determinado usuário. Por exemplo, você pode usar o cache da sessão em um aplicativo para armazenar a moeda favorita do usuário ou uma ordem personalizada de guias de navegação. Com o cache da sessão, você pode gerenciar valores de cache no Apex e ler valores em cache com uma variável global do Visualforce.

Ao usar o Apex, o gerenciamento do cache da sessão é semelhante ao do cache da organização, mas os nomes das classes são diferentes. Use as classes Cache.Session e Cache.SessionPartition para acessar valores armazenados no cache da sessão. Para gerenciar valores em qualquer partição, use os métodos na classe Cache.Session. Se você está administrando valores de cache em apenas uma partição, use os métodos de Cache.SessionPartition. Os métodos de Cache.SessionPartition são mais fáceis de usar que os métodos de Cache.Session porque você especifica o namespace e o prefixo da partição somente uma vez, na hora de criar o objeto de partição.

O trecho de código do Apex a seguir mostra como acessar uma partição para armazenar e recuperar um valor de cache. Ele obtém a partição chamada CurrencyCache no namespace local. Um novo valor é adicionado com a chave FavoriteCurrency. O valor da chave FavoriteCurrency é recuperado. A chave FavoriteCurrency armazena a moeda favorita do usuário, ou seja, esse valor é diferente para cada usuário e, portanto, um bom candidato para o cache da sessão.

// Get partition
Cache.SessionPartition sessionPart = Cache.Session.getPartition('local.CurrencyCache');
// Add cache value to the partition
sessionPart.put('FavoriteCurrency', 'JPY');
// Retrieve cache value from the partition
String cachedRate = (String)sessionPart.get('FavoriteCurrency');

Em uma página do Visualforce, acesse valores em cache armazenados no cache da plataforma usando as variáveis globais $Cache.Session ou $Cache.Org. Usando essas variáveis globais, você pode ler valores em cache que foram armazenados com Apex diretamente em sua página do Visualforce.

Nota

Os exemplos a seguir mostram como acessar o cache da sessão usando a variável global $Cache.Session. Os exemplos de cache da organização equivalentes são os mesmos, com a diferença de que você usa a variável global $Cache.Org.

Ao usar a variável global $Cache.Session, qualifique o nome da chave totalmente com o namespace e o nome da partição. Este exemplo é um componente de texto de saída que recupera um valor em cache de namespace ExPro, partição CurrencyCache e chave FavoriteCurrencyRate.

<apex:outputText value="{!$Cache.Session.ExPro.CurrencyCache.FavoriteCurrencyRate}"/>

Diferentemente dos métodos do Apex, você não pode omitir o prefixo namespace.partition para referenciar a partição padrão na organização. Se não houver namespace definido na organização, use local para fazer referência ao namespace da organização atual em que o código está sendo executado.

<apex:outputText value="{!$Cache.Session.local.MyPartition.Key}"/>

Se o valor em cache for uma estrutura de dados que tenha propriedades ou métodos, como uma lista do Apex ou uma classe personalizada, acesse essas propriedades na expressão $Cache.Session usando notação de pontos. Por exemplo, essa marcação invoca o método do Apex List.size() se o valor de numbersList está declarado como Lista.

<apex:outputText value="{!$Cache.Session.local.MyPartition.numbersList.size}"/>

O exemplo acessa a propriedade value no valor de cache myData que é declarado como uma classe personalizada.

<apex:outputText value="{!$Cache.Session.local.MyPartition.myData.value}"/>

Ao usar o cache da plataforma, os aplicativos ISV são executados mais rapidamente e têm melhor desempenho. Se você é um desenvolvedor de ISV, garanta espaço para seus aplicativos adquirindo espaço em cache para seu próprio namespace. Assim, quando seu aplicativo for instalado na organização de um assinante, o espaço do cache de seu aplicativo não será afetado pelo uso do cache na organização do assinante. Somente o código do Apex em execução a partir do namespace de seu aplicativo pode acessar e usar o cache do namespace. Nenhum outro código na organização do assinante pode usar esse cache. Você pode testar seu aplicativo em relação ao cache do namespace e verificar se a alocação de cache será protegida em todas as organizações de assinantes.

As partições de cache são distribuídas aos assinantes como parte do pacote do aplicativo. Adicione uma ou mais partições de cache de seu namespace ao pacote como componentes, da mesma forma que é feito com outros componentes. As partições de cache não são adicionadas automaticamente como componentes dependentes.

Nota

Consulte o seguinte em relação a partições no pacote:

• As partições adicionadas ao pacote precisam ser partições não padrão.
• Quando um assinante instalar seu pacote, as partições de cache serão instaladas em sua organização, permitindo que o aplicativo acesse as partições de cache instaladas para seu namespace.
• Os assinantes precisam ter uma organização Enterprise Edition ou uma Unlimited Edition, ou ter comprado Cache da plataforma.

O diagrama a seguir mostra um exemplo de capacidade de cache para uma organização de assinante da Enterprise Edition na qual um pacote foi instalado com cache. A capacidade total de cache do assinante de 30 MB é dividida em três partições que consistem em combinações de cache da sessão e organização. A capacidade de cache no pacote se origina do pacote instalado na organização do assinante e contém duas partições. O cache no pacote consiste em 20 MB de cache que o ISV comprou. (Lembre-se, somente o código do Apex do pacote pode acessar o cache no pacote; o código na organização do assinante não pode usar esse cache.)

Compre seu cache de namespace no aplicativo Channel Order. Você pode comprar cache em blocos de 10 MB. Para determinar a quantidade de espaço em cache exigida por seus aplicativos, teste-os com suas partições de cache. Use cache de avaliação para aumentar a capacidade de cache em sua organização. Como mencionado na primeira unidade, determinadas edições de organizações de assinantes recebem alocação de cache por padrão. Na organização Developer Edition em que você desenvolve aplicativos, é possível solicitar até 10 MB de cache de avaliação. Você pode solicitar o aumento da quantidade de cache de avaliação de sua organização entrando em contato com a Salesforce. Ao experimentar com diferentes tipos de cache, você terá uma ideia melhor do cache a ser comprado para seu próprio namespace.

Agora que você viu como obter e armazenar valores no Cache da plataforma, experimente! Conclua o desafio a seguir para testar seus conhecimentos.

Recursos no Apex Developer Guide:

• Platform Cache Partitions
• Apex Cache Namespace

Recursos em Ajuda do Salesforce: Cache Lightning Platform Data

Nota

Lembre-se: este módulo é destinado ao Salesforce Classic. Quando você iniciar sua organização prática, mude para o Salesforce Classic para concluir este desafio.