com.google.appengine.api.memcache
Interface MemcacheService

public interface MemcacheService

The Java API for the App Engine Memcache service. This offers a fast distrubted cache for commonly-used data. The cache is limited both in duration and also in total space, so objects stored in it may be discarded at any time.

Note that null is a legal value to store in the cache, or to use as a cache key. Although the API is written for Objects, both keys and values should be Serializable, although future versions may someday accept specific types of non-Serializable Objects.

The values returned from this API are mutable copies from the cache; altering them has no effect upon the cached value itself until assigned with one of the put methods. Likewise, the methods returning collections return mutable collections, but changes do not affect the cache.

Except for the increment(java.lang.Object, long) method, this service does not offer atomicity guarantees. In particular, the multi-key getAll(java.util.Collection), putAll(java.util.Map, com.google.appengine.api.memcache.Expiration, com.google.appengine.api.memcache.MemcacheService.SetPolicy), and deleteAll(java.util.Collection) operations are non-atomic.

Increment has a number of caveats to its use; please consult the method documentation.

Nested Class Summary

static class

MemcacheService.SetPolicy Cache replacement strategies for put(java.lang.Object, java.lang.Object, com.google.appengine.api.memcache.Expiration, com.google.appengine.api.memcache.MemcacheService.SetPolicy) operations, indicating how to handle putting a value that already exists.

Method Summary

void	clearAll() Empties the cache of all values.
boolean	contains(java.lang.Object key) Tests whether a given value is in cache, even if its value is null.
boolean	delete(java.lang.Object key) Removes key from the cache.
boolean	delete(java.lang.Object key, long millisNoReAdd) Removes the given key from the cache, and prevents it from being added under the MemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT policy for millisNoReAdd milliseconds thereafter.
java.util.Set<java.lang.Object>	deleteAll(java.util.Collection<java.lang.Object> keys) Batch version of delete(Object).
java.util.Set<java.lang.Object>	deleteAll(java.util.Collection<java.lang.Object> keys, long millisNoReAdd) Batch version of delete(Object, long).
java.lang.Object	get(java.lang.Object key) Fetches a previously-stored value, or null if unset.
java.util.Map<java.lang.Object,java.lang.Object>	getAll(java.util.Collection<java.lang.Object> keys) Performs a get of multiple keys at once.
ErrorHandler	getErrorHandler() Fetches the current error handler.
java.lang.String	getNamespace() Get the name of the namespace that will be used in API calls.
Stats	getStatistics() Fetches some statistics about the cache and its usage.
java.lang.Long	increment(java.lang.Object key, long delta) Atomically fetches, increments, and stores a given integral value.
void	put(java.lang.Object key, java.lang.Object value) A convenience shortcut, equivalent to put(key, value, null, SetPolicy.SET_ALWAYS).
void	put(java.lang.Object key, java.lang.Object value, Expiration expires) Convenience put, equivalent to put(key, value, expiration, SetPolicy.SET_ALWAYS).
boolean	put(java.lang.Object key, java.lang.Object value, Expiration expires, MemcacheService.SetPolicy policy) Store a new value into the cache, using key, but subject to the policy regarding existing entries.
void	putAll(java.util.Map<java.lang.Object,java.lang.Object> values) Convenience multi-put, equivalent to putAll(values, expires, SetPolicy.SET_ALWAYS).
void	putAll(java.util.Map<java.lang.Object,java.lang.Object> values, Expiration expires) Convenience multi-put, equivalent to putAll(values, expires, SetPolicy.SET_ALWAYS).
java.util.Set<java.lang.Object>	putAll(java.util.Map<java.lang.Object,java.lang.Object> values, Expiration expires, MemcacheService.SetPolicy policy) A batch-processing variant of put(java.lang.Object, java.lang.Object, com.google.appengine.api.memcache.Expiration, com.google.appengine.api.memcache.MemcacheService.SetPolicy).
void	setErrorHandler(ErrorHandler handler) Registers a new ErrorHandler.
void	setNamespace(java.lang.String newNamespace) Change the namespace used in API calls.

Method Detail

getNamespace

java.lang.String getNamespace()

Get the name of the namespace that will be used in API calls. This is initially set based on NamespaceManager.get().

setNamespace

void setNamespace(java.lang.String newNamespace)

Change the namespace used in API calls.

Parameters:

newNamespace - the new namespace to use. If null, switch back to the default namespace, as specified by NamespaceManager.get().

get

java.lang.Object get(java.lang.Object key)

Fetches a previously-stored value, or null if unset. Since null might be the set value in some cases, so we also have contains(Object) which returns boolean.

Parameters:

key - the key object used to store the cache entry

Returns:

the value object previously stored, or null

Throws:

java.lang.IllegalArgumentException - if the type of the key cannot be supported.

InvalidValueException - for any error in reconstituting the cache value.

contains

boolean contains(java.lang.Object key)

Tests whether a given value is in cache, even if its value is null.

Note that, because an object may be removed from cache at any time, the following is not sound code:

   if (memcache.contains("key")) {
     foo = memcache.get("key");
     if (foo == null) {
       // continue, assuming foo had the real value null
     }
   }
  

The problem is that the cache could have dropped the entry between the call to contains and @{link get. This is a sounder pattern:

   foo = memcache.get("key");
   if (foo == null) {
     if (memcache.contains("key")) {
       // continue, assuming foo had the real value null
     } else {
       // continue; foo may have had a real null, but has been dropped now
     }
   }
  

Another alternative is to prefer getAll(Collection), although it requires making an otherwise-unneeded Collection of some sort.

Parameters:

key - the key object used to store the cache entry

Returns:

true if the cache contains an entry for the key

Throws:

java.lang.IllegalArgumentException - if the key cannot be serialized

getAll

java.util.Map<java.lang.Object,java.lang.Object> getAll(java.util.Collection<java.lang.Object> keys)

Performs a get of multiple keys at once. This is more efficient than multiple separate calls to get(Object), and allows a single call to both test for contains(Object) and also fetch the value, because the return will not include mappings for keys not found.

Parameters:

keys - a collection of keys for which values should be retrieved

Returns:

a mapping from keys to values of any entries found. If a requested key is not found in the cache, the key will not be in the returned Map.

Throws:

java.lang.IllegalArgumentException - if an element of keys cannot be used as a cache key. They should be Serializable.

InvalidValueException - for any error in deserializing the cache value.

put

boolean put(java.lang.Object key,
            java.lang.Object value,
            Expiration expires,
            MemcacheService.SetPolicy policy)

Store a new value into the cache, using key, but subject to the policy regarding existing entries.

Parameters:

key - the key for the new cache entry

value - the value to be stored

expires - an Expiration object to set time-based expiration. null may be used indicate no specific expiration.

policy - Requests particular handling regarding pre-existing entries under the same key. This parameter must not be null.

Returns:

true if a new entry was created, false if not because of the policy.

Throws:

java.lang.IllegalArgumentException - if the key or value type can't be stored as a cache item. They should be Serializable.

put

void put(java.lang.Object key,
         java.lang.Object value,
         Expiration expires)

Convenience put, equivalent to put(key, value, expiration, SetPolicy.SET_ALWAYS).

Parameters:

key - key of the new entry

value - value for the new entry

expires - time-based Expiration, or null for none

Throws:

java.lang.IllegalArgumentException - if the key or value type can't be stored as a cache item. They should be Serializable.

put

void put(java.lang.Object key,
         java.lang.Object value)

A convenience shortcut, equivalent to put(key, value, null, SetPolicy.SET_ALWAYS).

Parameters:

key - key of the new entry

value - value for the new entry

Throws:

java.lang.IllegalArgumentException - if the key or value type can't be stored as a cache item. They should be Serializable.

putAll

java.util.Set<java.lang.Object> putAll(java.util.Map<java.lang.Object,java.lang.Object> values,
                                       Expiration expires,
                                       MemcacheService.SetPolicy policy)

A batch-processing variant of put(java.lang.Object, java.lang.Object, com.google.appengine.api.memcache.Expiration, com.google.appengine.api.memcache.MemcacheService.SetPolicy). This is more efficiently implemented by the service than multiple calls.

Parameters:

values - the key/value mappings to add to the cache

expires - the expiration time for all values, or null for no time-based expiration.

policy - what to do if the entry is or is not already present

Returns:

the set of keys for which entries were created. Keys in values may not be in the returned set because of the policy regarding pre-existing entries.

Throws:

java.lang.IllegalArgumentException - if the key or value type can't be stored as a cache item. They should be Serializable.

putAll

void putAll(java.util.Map<java.lang.Object,java.lang.Object> values,
            Expiration expires)

Convenience multi-put, equivalent to putAll(values, expires, SetPolicy.SET_ALWAYS).

Parameters:

values - key/value mappings to add to the cache

expires - expiration time for the new values, or null for no time-based expiration

Throws:

java.lang.IllegalArgumentException - if the key or value type can't be stored as a cache item. They should be Serializable.

putAll

void putAll(java.util.Map<java.lang.Object,java.lang.Object> values)

Convenience multi-put, equivalent to putAll(values, expires, SetPolicy.SET_ALWAYS).

Parameters:

values - key/value mappings for new entries to add to the cache

Throws:

java.lang.IllegalArgumentException - if the key or value type can't be stored as a cache item. They should be Serializable.

delete

boolean delete(java.lang.Object key)

Removes key from the cache.

Parameters:

key - the key of the entry to delete.

Returns:

true if an entry existed, but was discarded

Throws:

java.lang.IllegalArgumentException - if the key can't be used in the cache because it is not Serializable.

delete

boolean delete(java.lang.Object key,
               long millisNoReAdd)

Removes the given key from the cache, and prevents it from being added under the MemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT policy for millisNoReAdd milliseconds thereafter. Calls to a put(java.lang.Object, java.lang.Object, com.google.appengine.api.memcache.Expiration, com.google.appengine.api.memcache.MemcacheService.SetPolicy) method using MemcacheService.SetPolicy.SET_ALWAYS are not blocked, however.

Parameters:

key - key to delete

millisNoReAdd - time during which calls to put using ADD_IF_NOT_PRESENT should be denied.

Returns:

true if an entry existed to delete

Throws:

java.lang.IllegalArgumentException - if the key can't be used in the cache because it is not Serializable.

deleteAll

java.util.Set<java.lang.Object> deleteAll(java.util.Collection<java.lang.Object> keys)

Batch version of delete(Object).

Parameters:

keys - a collection of keys for entries to delete

Returns:

the Set of keys deleted. Any keys in keys but not in the returned set were not found in the cache.

Throws:

java.lang.IllegalArgumentException - if a key can't be used in the cache because it is not Serializable.

deleteAll

java.util.Set<java.lang.Object> deleteAll(java.util.Collection<java.lang.Object> keys,
                                          long millisNoReAdd)

Batch version of delete(Object, long).

Parameters:

keys - the keys to be deleted

millisNoReAdd - time during which calls to put using MemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT should be denied.

Returns:

the set of keys deleted.

Throws:

java.lang.IllegalArgumentException - if the key can't be used in the cache because it is not Serializable.

increment

java.lang.Long increment(java.lang.Object key,
                         long delta)

Atomically fetches, increments, and stores a given integral value. "Integral" types are Byte, Short, Integer, Long, and in some cases String (if the string is parseable as a number, for example via Long.parseLong(String). The entry must already exist, and have a non-negative value. To facilitate use as an atomic countdown, incremeting by a negative value (i.e. decrementing) will not go below zero: incrementing 2 by -5 will return 0, not -3.

Increment by positive amounts may wrap the value to become negative, creating an error for later increment operations. The value is considered as a 64-bit long during the increment, so the return value will wrap at 2^63 - 1, regardless of the actual storage type.

Parameters:

key - the key of the entry to manipulate

delta - the size of the increment, positive or negative.

Returns:

the post-increment value, as a long. However, a get(java.lang.Object) of the key will still have the original type (Byte, Short, etc.). If there is no entry for key, returns null.

Throws:

java.lang.IllegalArgumentException - if the key can't be used in the cache because it is not Serializable.

InvalidValueException - if the object incremented is not of a integral type

clearAll

void clearAll()

Empties the cache of all values. Statistics are not affected. Note that clearAll() does not respect namespaces - this flushes the cache for every namespace.

getStatistics

Stats getStatistics()

Fetches some statistics about the cache and its usage.

Returns:

statistics for the cache. Note that getStatistics() does not respect namespaces - this will return stats for every namespace. The response will never be null.

setErrorHandler

void setErrorHandler(ErrorHandler handler)

Registers a new ErrorHandler. The handler is used to field any errors which aren't necessarily the application programmer's fault: things like network timeouts, for example. Value correctness and usage errors IllegalArgumentException, InvalidValueException are still thrown normally.

Parameters:

handler - the new ErrorHandler to use. May not be null; use ErrorHandler#LOGGING_ERROR_HANDLER to explicitly restore default behavior.

getErrorHandler

ErrorHandler getErrorHandler()

Fetches the current error handler.