A API de cache de memória em Java oferece suporte à interface padrão JCache (javax.cache). Com o JCache, é possível definir e obter valores, controlar como os valores irão expirar do cache, inspecionar o conteúdo do cache e obter estatísticas sobre o cache. Você também pode usar "escutas" para adicionar um comportamento personalizado quando definir e excluir valores.
A API padrão do JCache ainda está sendo desenvolvida. A implementação do Google App Engine tenta implementar um subconjunto fiel. No entanto, considere usar a API de nível inferior do cache de memória para acessar mais recursos do serviço básico.
Para obter mais informações sobre o JCache, consulte JSR 107 e a especificação da API do JCache correspondente.
Use uma implementação da interface javax.cache.Cache para interagir com o cache. Para obter uma instância Cache, use uma CacheFactory, que por sua vez pode ser obtida por meio de um método estático no CacheManager. O código abaixo obtém uma instância Cache com as configurações padrão:
|
import java.util.Collections;
import javax.cache.Cache;
import javax.cache.CacheException;
import javax.cache.CacheFactory;
// ...
Cache cache;
try {
CacheFactory cacheFactory = CacheManager.getInstance().getCacheFactory();
cache = cacheFactory.createCache(Collections.emptyMap());
} catch (CacheException e) {
// ...
}
O método createCache() da CacheFactory assume um mapa de propriedades de configuração. Essas propriedades são discutidas abaixo. Para aceitar o padrão, forneça um mapa vazio ao método.
O Cache se comporta como um mapa: você armazena chaves e valores usando o método put() e recupera os valores usando o método get(). Qualquer objeto Serializable pode ser usado para a chave ou para 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 inserir vários valores, chame o método putAll() com um Map como argumento.
Para remover um valor do cache imediatamente, chame o método remove() com a chave como argumento. Para remover todos os valores do cache do aplicativo, chame o método clear().
O método containsKey() assume uma chave e retorna boolean (true ou false) para indicar se o cache contém um valor com aquela chave. O método isEmpty() testa se o cache está vazio. O método size() retorna o número de valores atualmente no cache.
Por padrão, todos os valores permanecem no cache o máximo possível, até serem removidos devido à pressão da memória, removidos explicitamente pelo aplicativo ou indisponibilizados por algum outro motivo (como uma interrupção). O aplicativo pode especificar um prazo de expiração para os valores, um período máximo de tempo durante o qual o valor estará disponível. O prazo de expiração pode ser definido como um período de tempo relativo a quando o valor é definido, ou como uma data e um horário absolutos.
É possível especificar a política de expiração usando as propriedades de configuração durante a criação da instância Cache. Todos os valores colocados nessa instância usam a mesma política de expiração. Por exemplo, para configurar uma instância Cache para expirar valores uma hora (3.600 segundos) depois de ser definida:
import java.util.Map;
import javax.cache.Cache;
import javax.cache.CacheException;
import javax.cache.CacheFactory;
import com.google.appengine.api.memcache.GCacheFactory;
// ...
Cache cache;
Map props = new Map;
props.put(GCacheFactory.EXPIRATION_DELTA, 3600);
try {
CacheFactory cacheFactory = CacheManager.getInstance().getCacheFactory();
cache = cacheFactory.createCache(props);
} catch (CacheException e) {
// ...
}
As propriedades abaixo controlam a expiração dos valores:
GCacheFactory.EXPIRATION_DELTA: expira os valores no período de tempo fornecido em relação a quando foram inseridos, como um número inteiro de segundos.GCacheFactory.EXPIRATION_DELTA_MILLIS: expira os valores no período de tempo fornecido em relação a quando foram inseridos, como um número inteiro de milissegundos.GCacheFactory.EXPIRATION: expira valores na data e no horário fornecidos, como um java.util.Date.Por padrão, a configuração de um valor no cache adiciona o valor se não houver nenhum valor com a chave fornecida e substitui um valor se houver um valor com a chave fornecida. Você pode configurar o cache para apenas adicionar (proteger os valores existentes) ou apenas substituir os valores (sem adicionar).
import java.util.Map;
import com.google.appengine.api.memcache.MemcacheService;
// ...
Map props = new Map;
props.put(MemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT, true);
As propriedades abaixo controlam a política de definição:
MemcacheService.SetPolicy.SET_ALWAYS: adiciona o valor se não houver valor com a chave, substitui um valor existente se houver um valor com a chave; este é o padrão.MemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT: adiciona o valor se não houver valor com a chave, não faz nada se houver valor.MemcacheService.SetPolicy.REPLACE_ONLY_IF_PRESENT: não faz nada se não houver valor com a chave, substitui um valor existente se houver um valor com a chave.O aplicativo pode recuperar as estatísticas sobre o seu próprio uso do cache. Essas estatísticas são úteis para monitorar e ajustar o comportamento do cache. O acesso às estatísticas é feito por meio do objeto CacheStatistics, adquirido ao chamar o método getCacheStatistics() da Cache.
As estatísticas disponíveis incluem o número de acessos ao cache (gets para chaves que existiam), o número de ausências de cache (gets para chaves que não existiam) e o número de valores no cache.
import javax.cache.CacheStatistics;
// ...
CacheStatistics stats = cache.getCacheStatistics();
int hits = stats.getCacheHits();
int misses = stats.getCacheMisses();
A implementação do Google App Engine não oferece suporte à redefinição da contagem de acessos e ausências do cache. Essa contagem é mantida indefinidamente, mas pode ser redefinida devido às condições temporárias dos servidores do cache de memória.
A API de escuta do JCache é suportada parcialmente para escutas que podem ser executadas durante o processamento de uma chamada da API do aplicativo, como no caso das escutas onPut e onRemove. As escutas que exigem processamento em segundo plano, como onEvict, não são suportadas.
Um aplicativo pode testar se o cache contém uma determinada chave, mas não pode testar se ele contém um determinado valor (containsValue() não é suportado).
Um aplicativo não pode descarregar o conteúdo das chaves ou dos valores do cache.
Um aplicativo não pode redefinir manualmente as estatísticas do cache.
Não há suporte para o carregamento assíncrono do cache.
O método put() não retorna o valor da chave conhecido anteriormente. Ele sempre retorna null.
A API de nível inferior para o serviço de cache de memória inclui métodos para incrementar e decrescer atomicamente valores inteiros do contador.
A API de nível inferior expõe mais estatísticas do cache, como o período de tempo desde o último acesso à entrada menos usada recentemente e o tamanho total de todos os itens no cache.
Para obter mais informações sobre a API de nível inferior, consulte o Javadoc do cache de memória .