使用 JCache

Memcache Java API 支持 JCache 标准接口 (javax.cache)。使用 JCache，您可以设置和获取值、控制值在缓存中到期的方法、检查缓存的内容，以及获取有关缓存的统计数据。您也可以使用“监听器”添加设置和删除值时的自定义行为。

JCache API 标准仍在开发中。App Engine 实现尝试实现一个忠实的子集。但是，您可能希望考虑使用低级 Memcache API 来访问底层服务的更多功能。

有关 JCache 的详细信息，请参阅 JSR 107 和相应的 JCache API 规范。

• 放置和获取值
• 配置过期
• 配置设置策略
• 缓存统计数据
• 不支持 JCache 功能
• 低级 API 的功能

获取一个 Cache 实例

使用 javax.cache.Cache 接口的实现来和缓存交互。使用从 CacheManager 上的静态方法获得的 CacheFactory 来获得一个 Cache 实例。以下代码获取具有默认配置的 Cache 实例：

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) {
            // ...
        }

CacheFactory 的 createCache() 方法采用配置属性的 Map。下文讨论这些属性。要接受默认，请为该方法提供一个空的 Map。

放置和获取值

Cache 的操作类似于 Map：使用 put() 方法存储键和值，然后使用 get() 方法检索值。您可以为键或值使用任何可序列化对象。

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

要放置多个值，可调用 putAll() 方法，以 Map 作为其参数。

要从缓存中删除一个值（立即驱逐），请调用 remove() 方法，以键作为其参数。要从应用程序的缓存中删除所有值，请调用 clear() 方法。

containsKey() 方法采用一个键，然后返回一个 boolean（true 或 false）以指示具有该键的值是否存在于缓存中。isEmpty() 方法测试缓存是否为空。size() 方法返回当前在缓存中的值的数目。

配置过期

默认情况下，所有值在缓存保留尽可能长的时间，直至由于内存的压力而被驱逐、应用程序显式删除，或由于其他原因（例如断电）而无法使用。应用程序可以指定值的过期时间，即值可用的最大时间量。过期时间可设置为相对于值的设置时间的时间量或设置为一个绝对的日期和时间。

创建 Cache 实例时使用配置属性指定过期策略。所有随该实例放置的值都将使用同一过期策略。例如，要将 Cache 实例配置为在值设置后一小时（3600 秒）后过期：

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) {
            // ...
        }

以下属性控制值过期：

• GCacheFactory.EXPIRATION_DELTA：在相对于值的放置时间的给定时间量（以整数秒数表示）后使值过期
• GCacheFactory.EXPIRATION_DELTA_MILLIS：在相对于值的放置时间的给定时间量（以整数毫秒数表示）后使值过期
• GCacheFactory.EXPIRATION：使值在给定日期和时间（以 java.util.Date 表示）后过期

配置设置策略

默认情况下，在缓存中设置值将在没有具有给定键的值的情况下添加值，而在已经存在具有给定键的值的情况下替换值。您可以将缓存配置为仅添加值（保护现有值）或仅替换值（不添加）。

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

以下属性控制设置策略：

• MemcacheService.SetPolicy.SET_ALWAYS：如果不存在具有该键的值则添加值，如果存在具有该键的值则替换现有值；此为默认
• MemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT：如果不存在具有该键的值则添加值，如果存在该键则不执行任何操作
• MemcacheService.SetPolicy.REPLACE_ONLY_IF_PRESENT：如果不存在具有该键的值则不执行任何操作，如果存在具有该键的值则替换现有值

缓存统计数据

应用程序可以检索有关其对于缓存的使用的统计数据。这些统计数据可用于监视和调节缓存行为。可使用 CacheStatistics 对象访问统计数据，该对象可通过调用 Cache 的 getCacheStatistics() 方法获取。

可用统计数据包括缓存命中（获取存在的键）的数目、缓存未命中（获取不存在的键）的数目，以及缓存中值的数目。

import javax.cache.CacheStatistics;

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

App Engine 实现不支持重置命中和未命中计数。命中和未命中计数将无限期地保持，但是可能会由于 memcache 服务器的瞬时条件而重置。

不支持 JCache 功能

JCache 监听器 API 部分支持可在应用程序的 API 调用的处理期间执行的监听器，例如 onPut 和 onRemove 监听器。不支持需要后台处理的监听器，如 onEvict。

应用程序可以测试缓存是否包含给定键，但是不能测试缓存是否包含给定值（不支持 containsValue()）。

应用程序不可以转储缓存的键或值的内容。

应用程序不可以手动重置缓存统计数据。

不支持异步缓存载入。

put() 方法不返回键的先前已知值。其总是返回 null。

低级 API 的功能

针对 Memcache 服务的低级 API 包括原子递增和递减整数计数器值的方法。

低级 API 公开更多的缓存统计数据，例如自访问最近使用的条目以来的时间量，以及缓存中所有项的总大小。

有关低级 API 的详细信息，请参阅 Memcache Javadoc。