Como usar o Memcache

Nesta página, descrevemos como configurar e monitorar o serviço Memcache para seu aplicativo usando o Console do Google Cloud. Descrevemos também como fazer tarefas comuns usando a interface JCache e como processar gravações simultâneas usando a API App Engine Memcache para Java de nível baixo. Para saber mais sobre o Memcache, leia a Visão geral do Memcache.

Essa API é compatível com os ambientes de execução de primeira geração e pode ser usada ao fazer upgrade para os ambientes de execução de segunda geração correspondentes. Se você estiver atualizando para o ambiente de execução do Java 11/17 do App Engine, consulte o guia de migração para saber mais sobre as opções de migração para serviços incluídos legados.

Como configurar o Memcache

1. Acesse a página "Memcache" no Console do Google Cloud.
   Acessar a página "Memcache"

2. Selecione o nível de serviço do Memcache que você quer usar:

   • Compartilhado (padrão): é gratuito e fornece capacidade de cache com base no melhor esforço possível.
   • Dedicado: é cobrado por GB/hora do tamanho do cache e fornece capacidade de cache fixa atribuída exclusivamente ao seu aplicativo.

   Saiba mais sobre as classes de serviços disponíveis na Visão geral do Memcache.

Como usar o JCache

O SDK do App Engine para Java é compatível com a interface JCache (JSR 107) para acessar o Memcache. A interface está incluída no pacote javax.cache.

Com o JCache, é possível definir, receber, inspecionar o conteúdo e controlar a expiração de valores no cache, além de conseguir estatísticas sobre ele. Também é possível usar "listeners" para adicionar comportamento personalizado ao definir e excluir valores.

O App Engine tenta implementar um subconjunto fiel da API JCache padrão. Para mais informações sobre o JCache, consulte JSR 107. Portanto, em vez de usar JCache, é possível usar a API Memcache de nível baixo para acessar mais recursos do serviço subjacente.

Como conseguir uma instância de cache

Você usa uma implementação da interface javax.cache.Cache para interagir com o cache e conseguir uma instância de Cache usando um CacheFactory a partir de um método estático no CacheManager. O código a seguir contém uma instância de Cache com a configuração padrão:

import java.util.Collections;
import javax.cache.Cache;
import javax.cache.CacheException;
import javax.cache.CacheFactory;
import javax.cache.CacheManager;

// ...
        Cache cache;
        try {
            CacheFactory cacheFactory = CacheManager.getInstance().getCacheFactory();
            cache = cacheFactory.createCache(Collections.emptyMap());
        } catch (CacheException e) {
            // ...
        }

O método createCache() do CacheFactory usa um Mapa de propriedades de configuração as quais serão abordadas abaixo. Para aceitar o padrão, forneça ao método um Mapa vazio.

Como inserir e receber valores

O Cache se comporta como um Mapa: você armazena chaves e valores usando o método put() e recupera valores usando o método get(). É possível usar qualquer objeto Serializable para a chave ou o valor.

        String key;      // ...
        byte[] value;    // ...

        // Put the value into the cache.
        cache.put(key, value);

        // Get the value from the cache.
        value = (byte[]) cache.get(key);

Para colocar vários valores, é possível chamar o método putAll() com um Mapa como seu argumento.

Para remover um valor do cache (para eliminá-lo imediatamente), chame o método remove() com a chave como seu argumento. Para remover todo valor do cache para o aplicativo, chame o método clear().

O método containsKey() usa uma chave e retorna um boolean (true ou false) para indicar se há um valor com essa chave no cache. O método isEmpty() testa se o cache está vazio. O método size() retorna o número de valores atualmente no cache.

Como configurar a expiração

Por padrão, todos os valores permanecem no cache o máximo possível até que sejam eliminados devido à pressão da memória, removidos explicitamente pelo aplicativo ou tornem-se indisponíveis por outro motivo (por exemplo, uma interrupção). O aplicativo especifica um período de expiração para os valores, ou seja, um prazo máximo de tempo de disponibilidade para o valor que pode ser definido como um período em relação ao momento em que o valor é determinado ou como uma data/hora absoluta.

Especifique a política de expiração usando as propriedades de configuração ao criar a instância de Cache. Todos os valores inseridos nessa instância usam a mesma política de expiração. Por exemplo, para configurar uma instância de Cache para expirar os valores uma hora (3.600 segundos) depois de serem definidos:

import java.util.HashMap;
import java.util.Map;
import javax.cache.Cache;
import javax.cache.CacheException;
import javax.cache.CacheFactory;
import javax.cache.CacheManager;
import javax.concurrent.TimeUnit;
import com.google.appengine.api.memcache.jsr107cache.GCacheFactory;

// ...
        Cache cache;
        try {
            CacheFactory cacheFactory = CacheManager.getInstance().getCacheFactory();
            Map<Object, Object> properties = new HashMap<>();
            properties.put(GCacheFactory.EXPIRATION_DELTA, TimeUnit.HOURS.toSeconds(1));
            cache = cacheFactory.createCache(properties);
        } catch (CacheException e) {
            // ...
        }

Estas propriedades controlam a expiração de valores:

• GCacheFactory.EXPIRATION_DELTA: expira os valores com base na quantidade de tempo determinada, em relação ao momento em que eles foram inseridos, como um número Inteiro de segundos
• GCacheFactory.EXPIRATION_DELTA_MILLIS: expira os valores com base na quantidade de tempo determinada, em relação ao momento em que eles foram inseridos, como um número Inteiro de milissegundos
• GCacheFactory.EXPIRATION: expira os valores na data e hora determinadas, como um java.util.Date

Como configurar a política de definição

Por padrão, a definição de um valor no cache o adiciona caso ainda não haja um com a chave fornecida e o substitui se já houver. É possível configurar o cache para apenas adicionar (proteger os valores existentes) ou apenas substituir (não adicionar valores).

import java.util.HashMap;
import java.util.Map;
import com.google.appengine.api.memcache.MemcacheService;

// ...
        Map<Object, Object> properties = new HashMap<>();
        properties.put(MemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT, true);

A seguir, as propriedades que controlam a política de definição:

• MemcacheService.SetPolicy.SET_ALWAYS: adiciona o valor se não existir um valor com a chave, substitui um valor atual se existir um valor com a chave (esse é o padrão)
• MemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT: adiciona o valor se não existir um valor com a chave, não faz nada se a chave existir
• MemcacheService.SetPolicy.REPLACE_ONLY_IF_PRESENT: não faz nada se não existir um valor com a chave, substitui um valor atual se existir um valor com a chave

Como recuperar estatísticas de cache

O aplicativo pode recuperar estatísticas sobre o próprio uso do cache. Essas estatísticas são úteis para monitorar e ajustar o comportamento do cache. Acesse as estatísticas usando um objeto CacheStatistics, obtido chamando o método getCacheStatistics() do Cache.

Entre as estatísticas disponíveis estão o número de ocorrências em cache (recebimento de chaves que já existiam), o de ausências no cache (recebimento de chaves que não existiam) e o de valores no cache.

import javax.cache.CacheStatistics;

        CacheStatistics stats = cache.getCacheStatistics();
        int hits = stats.getCacheHits();
        int misses = stats.getCacheMisses();

A implementação do App Engine não é compatível com a redefinição das contagens de hit e miss mantidas indefinidamente, mas podem ser redefinidas devido às condições temporárias dos servidores do Memcache.

Como monitorar o Memcache no console do Google Cloud

1. Acesse a página "Memcache" no Console do Google Cloud.
   Acessar a página "Memcache"
   
2. Veja os seguintes relatórios:
   • Nível de serviço do Memcache: mostra se o aplicativo está usando o nível de serviço Compartilhado ou Dedicado. Se você for proprietário do projeto, poderá alternar entre os dois. Saiba mais sobre os níveis de serviço.
   • Taxa de acerto: mostra a porcentagem de solicitações de dados e o número bruto de solicitações de dados que foram exibidos do cache.
   • Itens no cache.
   • Idade do item mais antigo: a idade do item mais antigo armazenado em cache. Observe que a idade de um item é redefinida sempre que ele é usado, lido ou gravado.
   • Tamanho total do cache.

3. Você pode realizar uma destas ações:

   • Nova chave: adiciona uma nova chave ao cache.
   • Encontrar uma chave: recupera uma chave existente.
   • Limpar o cache: remove todos os pares de chave-valor do cache.

4. (Somente no Memcache dedicado) Consulte a lista de chaves com uso intenso.

   • "Chaves de uso intenso" são as que recebem mais de cem consultas por segundo (QPS, na sigla em inglês) no Memcache.
   • Essa lista inclui até 100 chaves de atalho, classificadas pelo QPS mais alto.

Processar gravações simultâneas

Se você atualizar o valor de uma chave de memcache que possa receber outras solicitações de gravação simultâneas, use os métodos do Memcache de nível baixo putIfUntouched e getIdentifiable em vez de put e get. Os métodos putIfUntouched e getIdentifiable evitam disputas ao permitir que várias solicitações que estão sendo processadas simultaneamente atualizem o valor da mesma chave do Memcache de maneira atômica.

O snippet de código abaixo mostra uma maneira de atualizar com segurança o valor de uma chave que pode ter solicitações de atualização simultânea de outros clientes:

@SuppressWarnings("serial")
public class MemcacheConcurrentServlet extends HttpServlet {

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException,
      ServletException {
    String path = req.getRequestURI();
    if (path.startsWith("/favicon.ico")) {
      return; // ignore the request for favicon.ico
    }

    String key = "count-concurrent";
    // Using the synchronous cache.
    MemcacheService syncCache = MemcacheServiceFactory.getMemcacheService();

    // Write this value to cache using getIdentifiable and putIfUntouched.
    for (long delayMs = 1; delayMs < 1000; delayMs *= 2) {
      IdentifiableValue oldValue = syncCache.getIdentifiable(key);
      byte[] newValue = oldValue == null
          ? BigInteger.valueOf(0).toByteArray()
              : increment((byte[]) oldValue.getValue()); // newValue depends on old value
      resp.setContentType("text/plain");
      resp.getWriter().print("Value is " + new BigInteger(newValue).intValue() + "\n");
      if (oldValue == null) {
        // Key doesn't exist. We can safely put it in cache.
        syncCache.put(key, newValue);
        break;
      } else if (syncCache.putIfUntouched(key, oldValue, newValue)) {
        // newValue has been successfully put into cache.
        break;
      } else {
        // Some other client changed the value since oldValue was retrieved.
        // Wait a while before trying again, waiting longer on successive loops.
        try {
          Thread.sleep(delayMs);
        } catch (InterruptedException e) {
          throw new ServletException("Error when sleeping", e);
        }
      }
    }
  }

  /**
   * Increments an integer stored as a byte array by one.
   * @param oldValue a byte array with the old value
   * @return         a byte array as the old value increased by one
   */
  private byte[] increment(byte[] oldValue) {
    long val = new BigInteger(oldValue).intValue();
    val++;
    return BigInteger.valueOf(val).toByteArray();
  }
}

Observação: esses métodos também estão disponíveis no AsyncMemcacheService.

Como refinamento extra ao código de amostra, é possível definir um limite para o número de tentativas. O objetivo é evitar bloqueios tão demorados que façam a solicitação do App Engine expirar.

Próximas etapas

• Saiba mais sobre o memcache na Visão geral do Memcache.
• Consulte a documentação sobre a API Memcache de nível mais baixo e sobre o JCache (em inglês).