使用 JCache

Memcache Java API 支援 JCache 標準介面 (javax.cache)。 使用 JCache，您可以設定和取得值、控制值在快取中的失效方式、檢查快取的內容以及取得與快取相關的資料統計。您也可以在取得和刪除值時，使用「接聽器」來新增自訂行為。

JCache API 標準目前仍在發展中。「應用服務引擎」實作嘗試實作一個專用的子集。然而，您可以考慮使用低階 Memcache API 來存取其他的底層服務功能。

如需 JCache 的詳細資訊，請參閱 JSR 107 與相關的 JCache API 規格。

• 放入和取得值
• 設定失效
• 設定 Set 原則
• 快取統計資料
• 不支援·JCache·功能
• 低階 API 的功能

取得 Cache 實例

使用 javax.cache.Cache 介面來與快取互動。您可以使用 CacheFactory 取得 Cache 實例，而 CacheFactory 可從 CacheManager 的方法中取得。下列程式碼會取得含預設設定的 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() 方法並搭配 key 做為其引數。若要在應用程式從快取移除所有值，請呼叫 clear() 方法。

containsKey() 方法接受 key，並傳回 boolean (true 或 false) 指出含該 key 的值是否在快取中。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

設定 Set 原則

根據預設，如果沒有含特定金鑰的值，則會在快取中設定值，如果有含特定金鑰的值，則會取代值。您可以設定快取只新增 (保護現有值) 或取代值 (不要新增)。

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 物件存取統計資料，這會讓您藉由呼叫快取的 getCacheStatistics() 方法取得統計資料。

可取得的統計資料包括快取的點擊次數 (針對存在的金鑰取得)、遺失的快取數 (針對不存在的金鑰取得) 以及快取中值的數量。

import javax.cache.CacheStatistics;

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

「應用服務引擎」實作不支援重設點擊和遺失計數。點擊和遺失計數會被無限期地保留，但可能因 memcache 伺服器中斷而重設。

不支援·JCache·功能

JCache listener API (JCache 接聽器 API) 會局部支援可在應用程式的 API 呼叫過程中執行的接聽器，例如 onPut 和 onRemove 接聽器。不支援需要在背景處理的接聽器，例如 onEvict。

應用程式可以測試快取是否包含特定金鑰，但它無法測試快取是否包含特定值 (不支援 containsValue())。

應用程式無法傾印快取之金鑰或值的內容。

應用程式無法手動重設快取統計資料。

不支援非同步快取載入。

put() 方法無法為金鑰傳回上一個已知的值。它永遠會傳回 null。

低階 API 的功能

Memcache 服務的低階 API 包括單一增量和減量整數計數器值的方法。

低階 API 可顯示更多的快取統計資料，例如自存取最早使用項目以來的時間，以及快取中所有項目的總大小。

如需低階 API 的詳細資訊，請參閱 Memcache Javadoc。