Package com.google.appengine.api.memcache

Interface MemcacheService

All Superinterfaces:

BaseMemcacheService

public interface MemcacheService
extends BaseMemcacheService

The Java API for the App Engine Memcache service. This offers a fast distributed 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.

Methods that operate on single entries, including increment(java.lang.Object, long), are atomic, while batch methods such as getAll(java.util.Collection<T>), putAll(java.util.Map<T, ?>, com.google.appengine.api.memcache.Expiration, com.google.appengine.api.memcache.MemcacheService.SetPolicy), and deleteAll(java.util.Collection<T>) do not provide atomicity. Arbitrary operations on single entries can be performed atomically by using putIfUntouched(java.lang.Object, com.google.appengine.api.memcache.MemcacheService.IdentifiableValue, java.lang.Object, com.google.appengine.api.memcache.Expiration) in combination with getIdentifiable(java.lang.Object).

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

An ErrorHandler configures how errors are treated. The default error handler is an instance of LogAndContinueErrorHandler. In most cases this will log the underlying error condition and emulate cache-miss behavior instead of throwing an error to the calling code. For example, it returns null from get(Object).

A less permissive alternative is StrictErrorHandler, which will instead throw a MemcacheServiceException to expose any errors for application code to resolve.

To guarantee that all MemcacheServiceException are directed to the error handler use a ConsistentErrorHandler such as ErrorHandlers.getConsistentLogAndContinue(Level) or ErrorHandlers.getStrict().

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	MemcacheService.CasValues	A holder for compare and set values.
static interface	MemcacheService.IdentifiableValue	Encapsulates an Object that is returned by getIdentifiable(java.lang.Object).
static interface	MemcacheService.ItemForPeek	...
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

Modifier and Type	Method	Description
void	clearAll()	Empties the cache of all values across all namespaces.
boolean	contains(Object key)	Tests whether a given value is in cache, even if its value is null.
boolean	delete(Object key)	Removes key from the cache.
boolean	delete(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.
<T> Set<T>	deleteAll(Collection<T> keys)	Batch version of delete(Object).
<T> Set<T>	deleteAll(Collection<T> keys, long millisNoReAdd)	Batch version of delete(Object, long).
Object	get(Object key)	Fetches a previously-stored value, or null if unset.
<T> Map<T,Object>	getAll(Collection<T> keys)	Performs a get of multiple keys at once.
MemcacheService.IdentifiableValue	getIdentifiable(Object key)	Similar to get(java.lang.Object), but returns an object that can later be used to perform a putIfUntouched(java.lang.Object, com.google.appengine.api.memcache.MemcacheService.IdentifiableValue, java.lang.Object, com.google.appengine.api.memcache.Expiration) operation.
<T> Map<T,MemcacheService.IdentifiableValue>	getIdentifiables(Collection<T> keys)	Performs a getIdentifiable for multiple keys at once.
default MemcacheService.ItemForPeek	getItemForPeek(Object key)	Similar to get(java.lang.Object), but returns an object that can provide extra timestamp metadata.
default <T> Map<T,MemcacheService.ItemForPeek>	getItemsForPeek(Collection<T> keys)	Performs a getItemForPeek for multiple keys at once.
Stats	getStatistics()	Fetches some statistics about the cache and its usage.
Long	increment(Object key, long delta)	Atomically fetches, increments, and stores a given integral value.
Long	increment(Object key, long delta, Long initialValue)	Like normal increment, but allows for an optional initial value for the key to take on if not already present in the cache.
<T> Map<T,Long>	incrementAll(Collection<T> keys, long delta)	Like normal increment, but increments a batch of separate keys in parallel by the same delta.
<T> Map<T,Long>	incrementAll(Collection<T> keys, long delta, Long initialValue)	Like normal increment, but increments a batch of separate keys in parallel by the same delta and potentially sets a starting value.
<T> Map<T,Long>	incrementAll(Map<T,Long> offsets)	Like normal increment, but accepts a mapping of separate controllable offsets for each key individually.
<T> Map<T,Long>	incrementAll(Map<T,Long> offsets, Long initialValue)	Like normal increment, but accepts a mapping of separate controllable offsets for each key individually.
void	put(Object key, Object value)	A convenience shortcut, equivalent to put(key, value, null, SetPolicy.SET_ALWAYS).
void	put(Object key, Object value, Expiration expires)	Convenience put, equivalent to put(key, value, expiration, SetPolicy.SET_ALWAYS).
boolean	put(Object key, 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(Map<?,?> values)	Convenience multi-put, equivalent to putAll(values, expires, SetPolicy.SET_ALWAYS).
void	putAll(Map<?,?> values, Expiration expires)	Convenience multi-put, equivalent to putAll(values, expires, SetPolicy.SET_ALWAYS).
<T> Set<T>	putAll(Map<T,?> 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).
boolean	putIfUntouched(Object key, MemcacheService.IdentifiableValue oldValue, Object newValue)	Convenience shortcut, equivalent to put(key, oldValue, newValue, null).
boolean	putIfUntouched(Object key, MemcacheService.IdentifiableValue oldValue, Object newValue, Expiration expires)	Atomically, store newValue only if no other value has been stored since oldValue was retrieved.
<T> Set<T>	putIfUntouched(Map<T,MemcacheService.CasValues> values)	Convenience shortcut, equivalent to putIfUntouched(values, null).
<T> Set<T>	putIfUntouched(Map<T,MemcacheService.CasValues> values, Expiration expiration)	A batch-processing variant of putIfUntouched(Object, IdentifiableValue,Object,Expiration).
void	setNamespace(String newNamespace)	Deprecated. use MemcacheServiceFactory.getMemcacheService(String) instead.

Methods inherited from interface com.google.appengine.api.memcache.BaseMemcacheService

getErrorHandler, getNamespace, setErrorHandler

Method Detail

setNamespace

@Deprecated
void setNamespace(String newNamespace)

Deprecated.

use MemcacheServiceFactory.getMemcacheService(String) instead.

get

Object get(Object key)

Fetches a previously-stored value, or null if unset. To distinguish a null value from unset use contains(Object).

If an error deserializing the value occurs, this passes an InvalidValueException to the service's ErrorHandler. If a service error occurs, this passes a MemcacheServiceException. See BaseMemcacheService.setErrorHandler(ErrorHandler).

Parameters:

key - the key object used to store the cache entry

Returns:

the value object previously stored, or null

Throws:

IllegalArgumentException - if key is not Serializable and is not null

getIdentifiable

MemcacheService.IdentifiableValue getIdentifiable(Object key)

Similar to get(java.lang.Object), but returns an object that can later be used to perform a putIfUntouched(java.lang.Object, com.google.appengine.api.memcache.MemcacheService.IdentifiableValue, java.lang.Object, com.google.appengine.api.memcache.Expiration) operation.

If an error deserializing the value occurs, this passes an InvalidValueException to the service's ErrorHandler. If a service error occurs, this passes a MemcacheServiceException. See BaseMemcacheService.setErrorHandler(ErrorHandler).

Parameters:

key - the key object used to store the cache entry

Returns:

an MemcacheService.IdentifiableValue object that wraps the value object previously stored. null is returned if key is not present in the cache.

Throws:

IllegalArgumentException - if key is not Serializable and is not null

getItemForPeek

default MemcacheService.ItemForPeek getItemForPeek(Object key)

Similar to get(java.lang.Object), but returns an object that can provide extra timestamp metadata.

If an error deserializing the value occurs, this passes an InvalidValueException to the service's ErrorHandler. If a service error occurs, this passes a MemcacheServiceException. See BaseMemcacheService.setErrorHandler(ErrorHandler).

Parameters:

key - the key object used to store the cache entry

Returns:

an MemcacheService.ItemForPeek object that wraps the value object stored as well as extra meta data timestamps. null is returned if key is not present in the cache.

Throws:

IllegalArgumentException - if key is not Serializable and is not null

getIdentifiables

<T> Map<T,MemcacheService.IdentifiableValue> getIdentifiables(Collection<T> keys)

Performs a getIdentifiable for multiple keys at once. This is more efficient than multiple separate calls to getIdentifiable(Object).

If an error deserializing the value occurs, this passes an InvalidValueException to the service's ErrorHandler. If a service error occurs, this passes a MemcacheServiceException. See BaseMemcacheService.setErrorHandler(ErrorHandler).

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:

IllegalArgumentException - if any element of keys is not Serializable and is not null

getItemsForPeek

default <T> Map<T,MemcacheService.ItemForPeek> getItemsForPeek(Collection<T> keys)

Performs a getItemForPeek for multiple keys at once. This is more efficient than multiple separate calls to getItemForPeek(Object).

If an error deserializing the value occurs, this passes an InvalidValueException to the service's ErrorHandler. If a service error occurs, this passes a MemcacheServiceException. See BaseMemcacheService.setErrorHandler(ErrorHandler).

Parameters:

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

Returns:

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

Throws:

IllegalArgumentException - if any element of keys is not Serializable and is not null

contains

boolean contains(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(java.lang.Object) and get(Object). 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:

IllegalArgumentException - if key is not Serializable and is not null

getAll

<T> Map<T,Object> getAll(Collection<T> 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.

If an error deserializing the value occurs, this passes an InvalidValueException to the service's ErrorHandler. If a service error occurs, this passes a MemcacheServiceException. See BaseMemcacheService.setErrorHandler(ErrorHandler).

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:

IllegalArgumentException - if any element of keys is not Serializable and is not null

InvalidValueException - for any error in deserializing the cache value

put

boolean put(Object key,
            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:

IllegalArgumentException - if key or value is not Serializable and is not null

MemcacheServiceException - if server responds with an error and a ConsistentErrorHandler is not configured

put

void put(Object key,
         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:

IllegalArgumentException - if key or value is not Serializable and is not null

MemcacheServiceException - if server responds with an error and a ConsistentErrorHandler is not configured

put

void put(Object key,
         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:

IllegalArgumentException - if key or value is not Serializable and is not null

MemcacheServiceException - if server responds with an error and a ConsistentErrorHandler is not configured

putAll

<T> Set<T> putAll(Map<T,?> 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:

IllegalArgumentException - if any of the keys or values are not Serializable and are not null

MemcacheServiceException - if server responds with an error for any of the given values and a ConsistentErrorHandler is not configured

putAll

void putAll(Map<?,?> 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:

IllegalArgumentException - if any of the keys or values are not Serializable and are not null

MemcacheServiceException - if server responds with an error for any of the given values and a ConsistentErrorHandler is not configured

putAll

void putAll(Map<?,?> 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:

IllegalArgumentException - if any of the keys or values are not Serializable and are not null

MemcacheServiceException - if server responds with an error for any of the given values and a ConsistentErrorHandler is not configured

putIfUntouched

boolean putIfUntouched(Object key,
                       MemcacheService.IdentifiableValue oldValue,
                       Object newValue,
                       Expiration expires)

Atomically, store newValue only if no other value has been stored since oldValue was retrieved. oldValue is an MemcacheService.IdentifiableValue that was returned from a previous call to getIdentifiable(java.lang.Object).

If another value in the cache for key has been stored, or if this cache entry has been evicted, then nothing is stored by this call and false is returned.

Note that storing the same value again does count as a "touch" for this purpose.

Using getIdentifiable(java.lang.Object) and putIfUntouched(java.lang.Object, com.google.appengine.api.memcache.MemcacheService.IdentifiableValue, java.lang.Object, com.google.appengine.api.memcache.Expiration) together constitutes an operation that either succeeds atomically or fails due to concurrency (or eviction), in which case the entire operation can be retried by the application.

Parameters:

key - key of the entry

oldValue - identifier for the value to compare against newValue

newValue - new value to store if oldValue is still there

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

Returns:

true if newValue was stored, false otherwise

Throws:

IllegalArgumentException - if key or newValue is not Serializable and is not null. Also throws IllegalArgumentException if oldValue is null.

MemcacheServiceException - if server responds with an error and a ConsistentErrorHandler is not configured

putIfUntouched

boolean putIfUntouched(Object key,
                       MemcacheService.IdentifiableValue oldValue,
                       Object newValue)

Convenience shortcut, equivalent to put(key, oldValue, newValue, null).

Parameters:

key - key of the entry

oldValue - identifier for the value to compare against newValue

newValue - new value to store if oldValue is still there

Returns:

true if newValue was stored, false otherwise.

Throws:

IllegalArgumentException - if key or newValue is not Serializable and is not null. Also throws IllegalArgumentException if oldValue is null.

MemcacheServiceException - if server responds with an error and a ConsistentErrorHandler is not configured

putIfUntouched

<T> Set<T> putIfUntouched(Map<T,MemcacheService.CasValues> values)

Convenience shortcut, equivalent to putIfUntouched(values, null).

Parameters:

values - the key/values mappings to compare and swap

Returns:

the set of keys for which the new value was stored.

Throws:

IllegalArgumentException - if any of the keys are not Serializable or any of the values are not Serializable or null

IllegalArgumentException - If any of the keys or newValues are not Serializable and are not null. Also throws IllegalArgumentException if values has any nulls.

MemcacheServiceException - if server responds with an error for any of the given values and a ConsistentErrorHandler is not configured

putIfUntouched

<T> Set<T> putIfUntouched(Map<T,MemcacheService.CasValues> values,
                          Expiration expiration)

A batch-processing variant of putIfUntouched(Object, IdentifiableValue,Object,Expiration). This is more efficient than multiple single value calls.

Parameters:

values - the key/values mappings to compare and swap

expiration - an Expiration object to set time-based expiration for a value with a null expiration value. null may be used to indicate no specific expiration.

Returns:

the set of keys for which the new value was stored.

Throws:

IllegalArgumentException - If any of the keys or newValues are not Serializable and are not null. Also throws IllegalArgumentException if values has any nulls.

MemcacheServiceException - if server responds with an error for any of the given values and a ConsistentErrorHandler is not configured

delete

boolean delete(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:

IllegalArgumentException - if key is not Serializable and is not null

delete

boolean delete(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:

IllegalArgumentException - if key is not Serializable and is not null

deleteAll

<T> Set<T> deleteAll(Collection<T> 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. The iteration order of the returned set matches the iteration order of the provided keys.

Throws:

IllegalArgumentException - if any element of keys is not Serializable and is not null

deleteAll

<T> Set<T> deleteAll(Collection<T> keys,
                     long millisNoReAdd)

Batch version of delete(Object, long).

Parameters:

keys - a collection of keys for entries to delete

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

Returns:

the Set of keys deleted. Any keys in keys but not in the returned set were not found in the cache. The iteration order of the returned set matches the iteration order of the provided keys.

Throws:

IllegalArgumentException - if any element of keys is not Serializable and is not null

increment

Long increment(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. The entry must already exist, and have a non-negative value.

Incrementing by positive amounts will reach signed 64-bit max ( 2^63 - 1) and then wrap-around to signed 64-bit min (-2^63 ), continuing increments from that point.

To facilitate use as an atomic countdown, incrementing by a negative value (i.e. decrementing) will not go below zero: incrementing 2 by -5 will return 0, not -3.

Note: The actual representation of all numbers in Memcache is a string. This means if you initially stored a number as a string (e.g., "10") and then increment it, everything will work properly.

When you get(Object) a key for a string value, wrapping occurs after exceeding the max value of an unsigned 64-bit number (2^64 - 1). When you get(Object) a key for a numerical type, wrapping occurs after exceeding the type max value.

If a service error occurs, this passes a MemcacheServiceException to the service's ErrorHandler. See BaseMemcacheService.setErrorHandler(ErrorHandler).

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(Object) of the key will still have the original type ( Byte, Short, etc.). If there is no entry for key, returns null.

Throws:

IllegalArgumentException - if key is not Serializable and is not null

InvalidValueException - if the object incremented is not of a integral type or holding a negative value

increment

Long increment(Object key,
               long delta,
               Long initialValue)

Like normal increment, but allows for an optional initial value for the key to take on if not already present in the cache.

Note, the provided initial value can be negative, which allows incrementing negative numbers. This is in contrast to the base version of this method, which requires a pre-existing value (e.g. one stored with put(java.lang.Object, java.lang.Object, com.google.appengine.api.memcache.Expiration, com.google.appengine.api.memcache.MemcacheService.SetPolicy)) to be non-negative prior to being incremented.

Parameters:

initialValue - value to insert into the cache if the key is not present

See Also:

increment(Object, long)

incrementAll

<T> Map<T,Long> incrementAll(Collection<T> keys,
                                   long delta)

Like normal increment, but increments a batch of separate keys in parallel by the same delta.

Returns:

mapping keys to their new values; values will be null if they could not be incremented or were not present in the cache

See Also:

increment(Object, long)

incrementAll

<T> Map<T,Long> incrementAll(Collection<T> keys,
                                   long delta,
                                   Long initialValue)

Like normal increment, but increments a batch of separate keys in parallel by the same delta and potentially sets a starting value.

Parameters:

initialValue - value to insert into the cache if the key is not present

Returns:

mapping keys to their new values; values will be null if they could not be incremented for whatever reason

See Also:

increment(Object, long)

incrementAll

<T> Map<T,Long> incrementAll(Map<T,Long> offsets)

Like normal increment, but accepts a mapping of separate controllable offsets for each key individually. Good for incrementing by a sum and a count in parallel.

Returns:

mapping keys to their new values; values will be null if they could not be incremented for whatever reason

See Also:

increment(Object, long)

incrementAll

<T> Map<T,Long> incrementAll(Map<T,Long> offsets,
                                   Long initialValue)

Like normal increment, but accepts a mapping of separate controllable offsets for each key individually. Good for incrementing by a sum and a count in parallel. Callers may also pass an initial value for the keys to take on if they are not already present in the cache.

Returns:

mapping keys to their new values; values will be null if they could not be incremented for whatever reason

See Also:

increment(Object, long)

clearAll

void clearAll()

Empties the cache of all values across all namespaces. Statistics are not affected.

getStatistics

Stats getStatistics()

Fetches some statistics about the cache and its usage.

Returns:

statistics for the cache. Note that this method returns aggregated Stats for all namespaces. Response will never be null.