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 インターフェースの実装を使用し、キャッシュを操作します。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() メソッドは、設定プロパティのマップを取得します。プロパティについては下記で説明します。デフォルト設定を使用するには、メソッドに空のマップを渡します。

値の設定および取得

キャッシュは、マップのように動作します。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() メソッドをコールします。

キャッシュから値を削除（直ちに強制的に削除）するには、キーを引数として remove() メソッドをコールします。アプリケーションのすべての値をキャッシュから削除するには、clear() メソッドをコールします。

containsKey() メソッドはキーを引数として使用し、boolean（true または false）を返して、その値を持つキーが存在するかどうかを示します。isEmpty() メソッドはキャッシュが空かどうかをテストします。size() メソッドはキャッシュに存在する値の数を返します。

有効期限の設定

デフォルトでは、メモリが少なくなって消去されるか、アプリケーションから明示的に削除されるか、別の理由（システム停止など）で利用できなくなるまで、すべての値は可能な限り長くキャッシュに保持されます。アプリケーションは値の有効期限、つまり、値を利用可能な最長時間を指定できます。有効期限は値を設定した時点からの相対的な経過時間か、絶対的な日時で指定します。

Cache インスタンスの作成時に、設定プロパティを使用して有効期限のポリシーを指定します。そのインスタンスに設定されたすべての値は、同じ有効期限ポリシーに従います。たとえば、1 時間（3,600 秒）の有効期限値の Cache インスタンスの設定方法は次のとおりです。

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() メソッドをコールして統計を取得します。

取得可能な統計は、キャッシュ ヒット件数（存在するキーへの get コール数）、キャッシュ ミス件数（存在しないキーへの get コール数）およびキャッシュ内の値の数です。

import javax.cache.CacheStatistics;

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

App Engine 実装はヒット数とミス数のリセットはサポートしていません。ヒット数とミス数は永続的に保持されますが、memcache サーバーの一時的な状況によってはリセットされることがあります。

サポートされていない JCache の機能

JCache listener API は、onPut リスナや onRemove リスナなど、アプリケーションの API コールの処理中に実行できるリスナに対しては一時的にサポートされます。onEvict などバックグラウンド処理が必要なリスナはサポートしていません。

アプリケーションは、キャッシュ内に指定されたキーがあるかどうかをテストすることができますが、指定された値があるかどうかはテストできません（containsValue() はサポートしていません）。

アプリケーションはキャッシュのキーまたは値の内容をダンプできません。

アプリケーションはキャッシュの統計を手動でリセットできません。

非同期のキャッシュ読み込みはサポートしていません。

put() メソッドは、キーの以前の値を返すことはできません。常に null を返します。

低レベル API の機能

Memcache サービスへの低レベル API には、整数カウンタの値をアトミック的に増やしたり減らしたりするためのメソッドが含まれます。

低レベル API は、最後に使用されてから最も時間が経過したエントリの経過時間や、キャッシュ内のすべてのアイテムの合計サイズなど、さらに多くのキャッシュ統計情報を取得できます。

低レベル API の詳細については、Memcache Javadoc をご覧ください。