API Memcache для Java поддерживает стандартный интерфейс JCache (javax.cache). С помощью JCache можно устанавливать или получать значения, управлять сроком хранения в кэше, проверять содержание кэша и получать по нему статистику. Кроме того, можно использовать "приемники" событий, чтобы добавить специальное поведение при установлении и удалении значений.
Стандарт JCache API находится в разработке. В реализации App Engine сделана попытка реализации приемлемого набора функций. Тем не менее, чтобы получить доступ к большинству функций входящей службы, рекомендуем использовать низкоуровневый API Memcache.
Дополнительная информация о JCache представлена в JSR 107 и соответствующей спецификации API JCache.
Чтобы управлять кэшем, используйте реализацию интерфейса javax.cache.Cache. Получите экземпляр класса 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() получает карту свойств конфигурации. Эти свойства описаны далее. Чтобы использовать значения по умолчанию, в методе укажите пустую карту.
Объект Cache действует как карта: ключи и значения сохраняются с помощью метода 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 укажите политику срока хранения с помощью свойств конфигурации. Все значения, добавленные с одним экземпляром, используют одну политику срока хранения. Например, чтобы настроить экземпляр класса 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 не поддерживает сброс статистики по количеству успешных и неуспешных попыток. Эта статистика поддерживается за весь срок, однако, она может быть сброшена в связи с условиями перехода серверов кэша памяти.
API приемников событий JCache частично поддерживается для приемников, которые можно использовать во время вызова API приложения, например onPut и onRemove. Однако не поддерживаются приемники событий, требующие фоновую обработку, например onEvict.
Приложение может проверить, содержится ли в кэше определенный ключ, но не может проверить, есть ли в нем указанное значение (метод containsValue() не поддерживается).
Приложение не может сделать дамп содержания ключей или значений кэша.
Оно не может вручную сбросить статистику по кэшу.
Асинхронная загрузка кэша не поддерживается.
Метод put() не вернет для ключа предыдущее значение. Результатом его вызова всегда будет null.
Низкоуровневый API службы Memcache включает методы для атомарного уменьшения или увеличения целых значений счетчика
Он предоставляет больше статистики по кэшу, такой как время с момента доступа к последней используемой записи и общий размер всех элементов в кэше.
Дополнительную информацию о низкоуровневом API можно получить в документации Javadoc по Memcache.