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 forObject
s, both keys and values should beSerializable
, 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 asgetAll(java.util.Collection<T>)
,putAll(java.util.Map<T, ?>, com.google.appengine.api.memcache.Expiration, com.google.appengine.api.memcache.MemcacheService.SetPolicy)
, anddeleteAll(java.util.Collection<T>)
do not provide atomicity. Arbitrary operations on single entries can be performed atomically by usingputIfUntouched(java.lang.Object, com.google.appengine.api.memcache.MemcacheService.IdentifiableValue, java.lang.Object, com.google.appengine.api.memcache.Expiration)
in combination withgetIdentifiable(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 ofLogAndContinueErrorHandler
. 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 returnsnull
fromget(Object)
.A less permissive alternative is
StrictErrorHandler
, which will instead throw aMemcacheServiceException
to expose any errors for application code to resolve.To guarantee that all
MemcacheServiceException
are directed to the error handler use aConsistentErrorHandler
such asErrorHandlers.getConsistentLogAndContinue(Level)
orErrorHandlers.getStrict()
.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface and Description static class
MemcacheService.CasValues
A holder for compare and set values.static interface
MemcacheService.IdentifiableValue
Encapsulates an Object that is returned bygetIdentifiable(java.lang.Object)
.static class
MemcacheService.SetPolicy
Cache replacement strategies forput(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
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method and Description void
clearAll()
Empties the cache of all values across all namespaces.boolean
contains(java.lang.Object key)
Tests whether a given value is in cache, even if its value isnull
.boolean
delete(java.lang.Object key)
Removeskey
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 theMemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT
policy formillisNoReAdd
milliseconds thereafter.<T> java.util.Set<T>
deleteAll(java.util.Collection<T> keys)
Batch version ofdelete(Object)
.<T> java.util.Set<T>
deleteAll(java.util.Collection<T> keys, long millisNoReAdd)
Batch version ofdelete(Object, long)
.java.lang.Object
get(java.lang.Object key)
Fetches a previously-stored value, ornull
if unset.<T> java.util.Map<T,java.lang.Object>
getAll(java.util.Collection<T> keys)
Performs a get of multiple keys at once.MemcacheService.IdentifiableValue
getIdentifiable(java.lang.Object key)
Similar toget(java.lang.Object)
, but returns an object that can later be used to perform aputIfUntouched(java.lang.Object, com.google.appengine.api.memcache.MemcacheService.IdentifiableValue, java.lang.Object, com.google.appengine.api.memcache.Expiration)
operation.<T> java.util.Map<T,MemcacheService.IdentifiableValue>
getIdentifiables(java.util.Collection<T> keys)
Performs a getIdentifiable for multiple keys at once.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.java.lang.Long
increment(java.lang.Object key, long delta, java.lang.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> java.util.Map<T,java.lang.Long>
incrementAll(java.util.Collection<T> keys, long delta)
Like normal increment, but increments a batch of separate keys in parallel by the same delta.<T> java.util.Map<T,java.lang.Long>
incrementAll(java.util.Collection<T> keys, long delta, java.lang.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> java.util.Map<T,java.lang.Long>
incrementAll(java.util.Map<T,java.lang.Long> offsets)
Like normal increment, but accepts a mapping of separate controllable offsets for each key individually.<T> java.util.Map<T,java.lang.Long>
incrementAll(java.util.Map<T,java.lang.Long> offsets, java.lang.Long initialValue)
Like normal increment, but accepts a mapping of separate controllable offsets for each key individually.void
put(java.lang.Object key, java.lang.Object value)
A convenience shortcut, equivalent toput(key, value, null, SetPolicy.SET_ALWAYS)
.void
put(java.lang.Object key, java.lang.Object value, Expiration expires)
Convenience put, equivalent toput(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, usingkey
, but subject to thepolicy
regarding existing entries.void
putAll(java.util.Map<?,?> values)
Convenience multi-put, equivalent toputAll(values, expires, SetPolicy.SET_ALWAYS)
.void
putAll(java.util.Map<?,?> values, Expiration expires)
Convenience multi-put, equivalent toputAll(values, expires, SetPolicy.SET_ALWAYS)
.<T> java.util.Set<T>
putAll(java.util.Map<T,?> values, Expiration expires, MemcacheService.SetPolicy policy)
<T> java.util.Set<T>
putIfUntouched(java.util.Map<T,MemcacheService.CasValues> values)
Convenience shortcut, equivalent toputIfUntouched(values, null)
.<T> java.util.Set<T>
putIfUntouched(java.util.Map<T,MemcacheService.CasValues> values, Expiration expiration)
A batch-processing variant ofputIfUntouched(Object, IdentifiableValue,Object,Expiration)
.boolean
putIfUntouched(java.lang.Object key, MemcacheService.IdentifiableValue oldValue, java.lang.Object newValue)
Convenience shortcut, equivalent toput(key, oldValue, newValue, null)
.boolean
putIfUntouched(java.lang.Object key, MemcacheService.IdentifiableValue oldValue, java.lang.Object newValue, Expiration expires)
Atomically, storenewValue
only if no other value has been stored sinceoldValue
was retrieved.void
setNamespace(java.lang.String newNamespace)
Deprecated.useMemcacheServiceFactory.getMemcacheService(String)
instead.-
Methods inherited from interface com.google.appengine.api.memcache.BaseMemcacheService
getErrorHandler, getNamespace, setErrorHandler
-
-
-
-
Method Detail
-
setNamespace
@Deprecated void setNamespace(java.lang.String newNamespace)
Deprecated. useMemcacheServiceFactory.getMemcacheService(String)
instead.
-
get
java.lang.Object get(java.lang.Object key)
Fetches a previously-stored value, ornull
if unset. To distinguish anull
value from unset usecontains(Object)
.If an error deserializing the value occurs, this passes an
InvalidValueException
to the service'sErrorHandler
. If a service error occurs, this passes aMemcacheServiceException
. SeeBaseMemcacheService.setErrorHandler(ErrorHandler)
.- Parameters:
key
- the key object used to store the cache entry- Returns:
- the value object previously stored, or
null
- Throws:
java.lang.IllegalArgumentException
- ifkey
is notSerializable
and is notnull
-
getIdentifiable
MemcacheService.IdentifiableValue getIdentifiable(java.lang.Object key)
Similar toget(java.lang.Object)
, but returns an object that can later be used to perform aputIfUntouched(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'sErrorHandler
. If a service error occurs, this passes aMemcacheServiceException
. SeeBaseMemcacheService.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 ifkey
is not present in the cache. - Throws:
java.lang.IllegalArgumentException
- ifkey
is notSerializable
and is notnull
-
getIdentifiables
<T> java.util.Map<T,MemcacheService.IdentifiableValue> getIdentifiables(java.util.Collection<T> keys)
Performs a getIdentifiable for multiple keys at once. This is more efficient than multiple separate calls togetIdentifiable(Object)
.If an error deserializing the value occurs, this passes an
InvalidValueException
to the service'sErrorHandler
. If a service error occurs, this passes aMemcacheServiceException
. SeeBaseMemcacheService.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:
java.lang.IllegalArgumentException
- if any element ofkeys
is notSerializable
and is notnull
-
contains
boolean contains(java.lang.Object key)
Tests whether a given value is in cache, even if its value isnull
.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 tocontains(java.lang.Object)
andget(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 prefergetAll(Collection)
, although it requires making an otherwise-unneededCollection
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
- ifkey
is notSerializable
and is notnull
-
getAll
<T> java.util.Map<T,java.lang.Object> getAll(java.util.Collection<T> keys)
Performs a get of multiple keys at once. This is more efficient than multiple separate calls toget(Object)
, and allows a single call to both test forcontains(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'sErrorHandler
. If a service error occurs, this passes aMemcacheServiceException
. SeeBaseMemcacheService.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:
java.lang.IllegalArgumentException
- if any element ofkeys
is notSerializable
and is notnull
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, usingkey
, but subject to thepolicy
regarding existing entries.- Parameters:
key
- the key for the new cache entryvalue
- the value to be storedexpires
- anExpiration
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 benull
.- Returns:
true
if a new entry was created,false
if not because of thepolicy
- Throws:
java.lang.IllegalArgumentException
- ifkey
orvalue
is notSerializable
and is notnull
MemcacheServiceException
- if server responds with an error and aConsistentErrorHandler
is not configured
-
put
void put(java.lang.Object key, java.lang.Object value, Expiration expires)
Convenience put, equivalent toput(key, value, expiration, SetPolicy.SET_ALWAYS)
.- Parameters:
key
- key of the new entryvalue
- value for the new entryexpires
- time-basedExpiration
, ornull
for none- Throws:
java.lang.IllegalArgumentException
- ifkey
orvalue
is notSerializable
and is notnull
MemcacheServiceException
- if server responds with an error and aConsistentErrorHandler
is not configured
-
put
void put(java.lang.Object key, java.lang.Object value)
A convenience shortcut, equivalent toput(key, value, null, SetPolicy.SET_ALWAYS)
.- Parameters:
key
- key of the new entryvalue
- value for the new entry- Throws:
java.lang.IllegalArgumentException
- ifkey
orvalue
is notSerializable
and is notnull
MemcacheServiceException
- if server responds with an error and aConsistentErrorHandler
is not configured
-
putAll
<T> java.util.Set<T> putAll(java.util.Map<T,?> values, Expiration expires, MemcacheService.SetPolicy policy)
A batch-processing variant ofput(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 cacheexpires
- the expiration time for allvalues
, ornull
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 thepolicy
regarding pre-existing entries. - Throws:
java.lang.IllegalArgumentException
- if any of the keys or values are notSerializable
and are notnull
MemcacheServiceException
- if server responds with an error for any of the given values and aConsistentErrorHandler
is not configured
-
putAll
void putAll(java.util.Map<?,?> values, Expiration expires)
Convenience multi-put, equivalent toputAll(values, expires, SetPolicy.SET_ALWAYS)
.- Parameters:
values
- key/value mappings to add to the cacheexpires
- expiration time for the new values, ornull
for no time-based expiration- Throws:
java.lang.IllegalArgumentException
- if any of the keys or values are notSerializable
and are notnull
MemcacheServiceException
- if server responds with an error for any of the given values and aConsistentErrorHandler
is not configured
-
putAll
void putAll(java.util.Map<?,?> values)
Convenience multi-put, equivalent toputAll(values, expires, SetPolicy.SET_ALWAYS)
.- Parameters:
values
- key/value mappings for new entries to add to the cache- Throws:
java.lang.IllegalArgumentException
- if any of the keys or values are notSerializable
and are notnull
MemcacheServiceException
- if server responds with an error for any of the given values and aConsistentErrorHandler
is not configured
-
putIfUntouched
boolean putIfUntouched(java.lang.Object key, MemcacheService.IdentifiableValue oldValue, java.lang.Object newValue, Expiration expires)
Atomically, storenewValue
only if no other value has been stored sinceoldValue
was retrieved.oldValue
is anMemcacheService.IdentifiableValue
that was returned from a previous call togetIdentifiable(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 andfalse
is returned.Note that storing the same value again does count as a "touch" for this purpose.
Using
getIdentifiable(java.lang.Object)
andputIfUntouched(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 entryoldValue
- identifier for the value to compare against newValuenewValue
- new value to store if oldValue is still thereexpires
- anExpiration
object to set time-based expiration.null
may be used to indicate no specific expiration.- Returns:
true
ifnewValue
was stored,false
otherwise- Throws:
java.lang.IllegalArgumentException
- ifkey
ornewValue
is notSerializable
and is notnull
. Also throws IllegalArgumentException ifoldValue
isnull
.MemcacheServiceException
- if server responds with an error and aConsistentErrorHandler
is not configured
-
putIfUntouched
boolean putIfUntouched(java.lang.Object key, MemcacheService.IdentifiableValue oldValue, java.lang.Object newValue)
Convenience shortcut, equivalent toput(key, oldValue, newValue, null)
.- Parameters:
key
- key of the entryoldValue
- identifier for the value to compare against newValuenewValue
- new value to store if oldValue is still there- Returns:
true
ifnewValue
was stored,false
otherwise.- Throws:
java.lang.IllegalArgumentException
- ifkey
ornewValue
is notSerializable
and is notnull
. Also throws IllegalArgumentException ifoldValue
isnull
.MemcacheServiceException
- if server responds with an error and aConsistentErrorHandler
is not configured
-
putIfUntouched
<T> java.util.Set<T> putIfUntouched(java.util.Map<T,MemcacheService.CasValues> values)
Convenience shortcut, equivalent toputIfUntouched(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:
java.lang.IllegalArgumentException
- if any of the keys are notSerializable
or any of the values are notSerializable
ornull
java.lang.IllegalArgumentException
- If any of the keys or newValues are notSerializable
and are notnull
. Also throws IllegalArgumentException ifvalues
has any nulls.MemcacheServiceException
- if server responds with an error for any of the givenvalues
and aConsistentErrorHandler
is not configured
-
putIfUntouched
<T> java.util.Set<T> putIfUntouched(java.util.Map<T,MemcacheService.CasValues> values, Expiration expiration)
A batch-processing variant ofputIfUntouched(Object, IdentifiableValue,Object,Expiration)
. This is more efficient than multiple single value calls.- Parameters:
values
- the key/values mappings to compare and swapexpiration
- anExpiration
object to set time-based expiration for avalue
with anull
expiration
value.null
may be used to indicate no specific expiration.- Returns:
- the set of keys for which the new value was stored.
- Throws:
java.lang.IllegalArgumentException
- If any of the keys or newValues are notSerializable
and are notnull
. Also throws IllegalArgumentException ifvalues
has any nulls.MemcacheServiceException
- if server responds with an error for any of the givenvalues
and aConsistentErrorHandler
is not configured
-
delete
boolean delete(java.lang.Object key)
Removeskey
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
- ifkey
is notSerializable
and is notnull
-
delete
boolean delete(java.lang.Object key, long millisNoReAdd)
Removes the given key from the cache, and prevents it from being added under theMemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT
policy formillisNoReAdd
milliseconds thereafter. Calls to aput(java.lang.Object, java.lang.Object, com.google.appengine.api.memcache.Expiration, com.google.appengine.api.memcache.MemcacheService.SetPolicy)
method usingMemcacheService.SetPolicy.SET_ALWAYS
are not blocked, however.- Parameters:
key
- key to deletemillisNoReAdd
- 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
- ifkey
is notSerializable
and is notnull
-
deleteAll
<T> java.util.Set<T> deleteAll(java.util.Collection<T> keys)
Batch version ofdelete(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 providedkeys
. - Throws:
java.lang.IllegalArgumentException
- if any element ofkeys
is notSerializable
and is notnull
-
deleteAll
<T> java.util.Set<T> deleteAll(java.util.Collection<T> keys, long millisNoReAdd)
Batch version ofdelete(Object, long)
.- Parameters:
keys
- a collection of keys for entries to deletemillisNoReAdd
- time during which calls to put usingMemcacheService.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 providedkeys
. - Throws:
java.lang.IllegalArgumentException
- if any element ofkeys
is notSerializable
and is notnull
-
increment
java.lang.Long increment(java.lang.Object key, long delta)
Atomically fetches, increments, and stores a given integral value. "Integral" types areByte
,Short
,Integer
,Long
, and in some casesString
. 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 return0
, 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 youget(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'sErrorHandler
. SeeBaseMemcacheService.setErrorHandler(ErrorHandler)
.- Parameters:
key
- the key of the entry to manipulatedelta
- 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 forkey
, returnsnull
. - Throws:
java.lang.IllegalArgumentException
- ifkey
is notSerializable
and is notnull
InvalidValueException
- if the object incremented is not of a integral type or holding a negative value
-
increment
java.lang.Long increment(java.lang.Object key, long delta, java.lang.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> java.util.Map<T,java.lang.Long> incrementAll(java.util.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> java.util.Map<T,java.lang.Long> incrementAll(java.util.Collection<T> keys, long delta, java.lang.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> java.util.Map<T,java.lang.Long> incrementAll(java.util.Map<T,java.lang.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> java.util.Map<T,java.lang.Long> incrementAll(java.util.Map<T,java.lang.Long> offsets, java.lang.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.
-
-