com.googlecode.objectify.cache

Class EntityMemcache

java.lang.Object

com.googlecode.objectify.cache.EntityMemcache

public class EntityMemcache
extends Object

This is the facade used by Objectify to cache entities in the MemcacheService.

Entity cacheability and expiration are determined by a CacheControl object. In addition, hit/miss statistics are tracked in a MemcacheStats.

In order to guarantee cache synchronization, getAll() *must* be able to return an IdentifiableValue, even for entries not present in the cache. Because empty cache values cannot be made into IdentifiableValue, we immediately replace them with a null value and refetch (null is a valid cache value). If this refetch doesn't work, we treat the key as uncacheable for the duration of the request.

The values put in memcache are Key -> Entity, except for negative cache entries, which are Key -> String (the value NEGATIVE).

Author:

Jeff Schnitzer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	EntityMemcache.Bucket A bucket represents memcache information for a particular Key.

Field Summary

Fields

Modifier and Type	Field and Description
static String	NEGATIVE The value stored in the memcache for a negative cache result.

Constructor Summary

Constructors

Constructor and Description
EntityMemcache(String namespace) Creates a memcache which caches everything without expiry and doesn't record statistics.
EntityMemcache(String namespace, CacheControl cacheControl) Creates a memcache which doesn't record stats
EntityMemcache(String namespace, CacheControl cacheControl, MemcacheStats stats)

Method Summary

Modifier and Type	Method and Description
void	empty(Iterable<com.google.appengine.api.datastore.Key> keys) Revert a set of keys to the empty state.
Map<com.google.appengine.api.datastore.Key,EntityMemcache.Bucket>	getAll(Iterable<com.google.appengine.api.datastore.Key> keys) Gets the Buckets for the specified keys.
static Set<com.google.appengine.api.datastore.Key>	keysOf(Iterable<EntityMemcache.Bucket> buckets) Basically a list comprehension of the keys for convenience.
void	putAll(Collection<EntityMemcache.Bucket> updates) Update a set of buckets with new values.
void	setErrorHandler(com.google.appengine.api.memcache.ErrorHandler handler) Sets the error handler for the non-retry memcache object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NEGATIVE

public static final String NEGATIVE

The value stored in the memcache for a negative cache result.

See Also:

Constant Field Values

Constructor Detail

EntityMemcache

public EntityMemcache(String namespace)

Creates a memcache which caches everything without expiry and doesn't record statistics.

EntityMemcache

public EntityMemcache(String namespace,
                      CacheControl cacheControl)

Creates a memcache which doesn't record stats

EntityMemcache

public EntityMemcache(String namespace,
                      CacheControl cacheControl,
                      MemcacheStats stats)

Method Detail

setErrorHandler

public void setErrorHandler(com.google.appengine.api.memcache.ErrorHandler handler)

Sets the error handler for the non-retry memcache object.

getAll

public Map<com.google.appengine.api.datastore.Key,EntityMemcache.Bucket> getAll(Iterable<com.google.appengine.api.datastore.Key> keys)

Gets the Buckets for the specified keys. A bucket is built around an IdentifiableValue so you can putAll() them without the risk of overwriting other threads' changes. Buckets also hide the underlying details of storage for negative, empty, and uncacheable results.

Note that worst case (a cold cache), obtaining each bucket might require three memcache requests: a getIdentifiable() which returns null, a put(EMPTY), and another getIdentifiable(). Since there is no batch getIdentifiable(), this is *per key*.

When keys are uncacheable (per CacheControl) or the memcache is down, you will still get an empty bucket back. The bucket will have null IdentifiableValue so we can identify it as uncacheable.

Returns:

the buckets requested. Buckets will never be null. You will always get a bucket for every key.

putAll

public void putAll(Collection<EntityMemcache.Bucket> updates)

Update a set of buckets with new values. If collisions occur, resets the memcache value to null.

Parameters:

updates - can have null Entity values, which will record a negative cache result. Buckets must have been obtained from getAll().

empty

public void empty(Iterable<com.google.appengine.api.datastore.Key> keys)

Revert a set of keys to the empty state. Will loop on this several times just in case the memcache write fails - we don't want to leave the cache in a nasty state.

keysOf

public static Set<com.google.appengine.api.datastore.Key> keysOf(Iterable<EntityMemcache.Bucket> buckets)

Basically a list comprehension of the keys for convenience.