public interface MemcacheService extends BaseMemcacheService
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
Object
s, 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.
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 by
getIdentifiable(java.lang.Object)
.
|
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.
|
Modifier and Type | Method and Description |
---|---|
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.
|
<T> java.util.Set<T>
|
deleteAll
(java.util.Collection<T> keys)
Batch version of
delete(Object)
.
|
<T> java.util.Set<T>
|
deleteAll
(java.util.Collection<T> 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.
|
<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 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> 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 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<?,?> values)
Convenience multi-put, equivalent to
putAll(values, expires, SetPolicy.SET_ALWAYS)
.
|
void
|
putAll
(java.util.Map<?,?> values,
Expiration
expires)
Convenience multi-put, equivalent to
putAll(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 to
putIfUntouched(values, null)
.
|
<T> java.util.Set<T>
|
putIfUntouched
(java.util.Map<T,
MemcacheService.CasValues
> values,
Expiration
expiration)
A batch-processing variant of
putIfUntouched(Object,
IdentifiableValue,Object,Expiration)
.
|
boolean
|
putIfUntouched
(java.lang.Object key,
MemcacheService.IdentifiableValue
oldValue,
java.lang.Object newValue)
Convenience shortcut, equivalent to
put(key, oldValue, newValue, null)
.
|
boolean
|
putIfUntouched
(java.lang.Object key,
MemcacheService.IdentifiableValue
oldValue,
java.lang.Object newValue,
Expiration
expires)
Atomically, store
newValue
only if no other value has been stored
since
oldValue
was retrieved.
|
void
|
setNamespace
(java.lang.String newNamespace)
Deprecated.
use
MemcacheServiceFactory.getMemcacheService(String)
instead.
|
getErrorHandler
,
getNamespace
,
setErrorHandler
@Deprecated void setNamespace(java.lang.String newNamespace)
MemcacheServiceFactory.getMemcacheService(String)
instead.
java.lang.Object get(java.lang.Object key)
null
if unset. To
distinguish a
null
value from unset use
contains(Object)
.
key
- the key object used to store the cache entry
null
java.lang.IllegalArgumentException
- if
key
is not
Serializable
and is not
null
InvalidValueException
- for any error in reconstituting the cache
value.
MemcacheService.IdentifiableValue getIdentifiable(java.lang.Object key)
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.
key
- the key object used to store the cache entry
MemcacheService.IdentifiableValue
object that wraps the
value object previously stored.
null
is returned if
key
is not present in the cache.
java.lang.IllegalArgumentException
- if
key
is not
Serializable
and is not
null
InvalidValueException
- for any error in reconstituting the cache
value
<T> java.util.Map<T,MemcacheService.IdentifiableValue> getIdentifiables(java.util.Collection<T> keys)
getIdentifiable(Object)
.
keys
- a collection of keys for which values should be retrieved
java.lang.IllegalArgumentException
- if any element of
keys
is not
Serializable
and is not
null
InvalidValueException
- for any error in deserializing the cache
value
boolean contains(java.lang.Object key)
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.
key
- the key object used to store the cache entry
true
if the cache contains an entry for the key
java.lang.IllegalArgumentException
- if
key
is not
Serializable
and is not
null
<T> java.util.Map<T,java.lang.Object> getAll(java.util.Collection<T> keys)
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.
keys
- a collection of keys for which values should be retrieved
java.lang.IllegalArgumentException
- if any element of
keys
is not
Serializable
and is not
null
InvalidValueException
- for any error in deserializing the cache
value
boolean put(java.lang.Object key, java.lang.Object value, Expiration expires, MemcacheService.SetPolicy policy)
key
, but subject to the
policy
regarding existing entries.
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
.
true
if a new entry was created,
false
if not
because of the
policy
java.lang.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
void put(java.lang.Object key, java.lang.Object value, Expiration expires)
put(key, value, expiration, SetPolicy.SET_ALWAYS)
.
key
- key of the new entry
value
- value for the new entry
expires
- time-based
Expiration
, or
null
for none
java.lang.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
void put(java.lang.Object key, java.lang.Object value)
put(key, value, null, SetPolicy.SET_ALWAYS)
.
key
- key of the new entry
value
- value for the new entry
java.lang.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
<T> java.util.Set<T> putAll(java.util.Map<T,?> values, Expiration expires, MemcacheService.SetPolicy policy)
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.
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
values
may not be in the returned set because of the
policy
regarding pre-existing entries.
java.lang.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
void putAll(java.util.Map<?,?> values, Expiration expires)
putAll(values, expires, SetPolicy.SET_ALWAYS)
.
values
- key/value mappings to add to the cache
expires
- expiration time for the new values, or
null
for no
time-based expiration
java.lang.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
void putAll(java.util.Map<?,?> values)
putAll(values, expires, SetPolicy.SET_ALWAYS)
.
values
- key/value mappings for new entries to add to the cache
java.lang.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
boolean putIfUntouched(java.lang.Object key, MemcacheService.IdentifiableValue oldValue, java.lang.Object newValue, Expiration expires)
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.
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.
true
if
newValue
was stored,
false
otherwise
java.lang.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
boolean putIfUntouched(java.lang.Object key, MemcacheService.IdentifiableValue oldValue, java.lang.Object newValue)
put(key, oldValue, newValue, null)
.
key
- key of the entry
oldValue
- identifier for the value to compare against newValue
newValue
- new value to store if oldValue is still there
true
if
newValue
was stored,
false
otherwise.
java.lang.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
<T> java.util.Set<T> putIfUntouched(java.util.Map<T,MemcacheService.CasValues> values)
putIfUntouched(values, null)
.
values
- the key/values mappings to compare and swap
java.lang.IllegalArgumentException
- if any of the keys are not
Serializable
or any of the values are not
Serializable
or
null
java.lang.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
<T> java.util.Set<T> putIfUntouched(java.util.Map<T,MemcacheService.CasValues> values, Expiration expiration)
putIfUntouched(Object,
IdentifiableValue,Object,Expiration)
. This is more efficient than
multiple single value calls.
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.
java.lang.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
boolean delete(java.lang.Object key)
key
from the cache.
key
- the key of the entry to delete.
true
if an entry existed, but was discarded
java.lang.IllegalArgumentException
- if
key
is not
Serializable
and is not
null
boolean delete(java.lang.Object key, long millisNoReAdd)
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.
key
- key to delete
millisNoReAdd
- time during which calls to put using
ADD_IF_NOT_PRESENT should be denied.
true
if an entry existed to delete
java.lang.IllegalArgumentException
- if
key
is not
Serializable
and is not
null
<T> java.util.Set<T> deleteAll(java.util.Collection<T> keys)
delete(Object)
.
keys
- a collection of keys for entries to delete
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
.
java.lang.IllegalArgumentException
- if any element of
keys
is not
Serializable
and is not
null
<T> java.util.Set<T> deleteAll(java.util.Collection<T> keys, long millisNoReAdd)
delete(Object, long)
.
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.
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
.
java.lang.IllegalArgumentException
- if any element of
keys
is not
Serializable
and is not
null
java.lang.Long increment(java.lang.Object key, long delta)
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.
key
- the key of the entry to manipulate
delta
- the size of the increment, positive or negative
get(Object)
of the key will still have the original type (
Byte
,
Short
, etc.). If there is no entry for
key
, returns
null
.
java.lang.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
java.lang.Long increment(java.lang.Object key, long delta, java.lang.Long initialValue)
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.
initialValue
- value to insert into the cache if the key is not
present
increment(Object, long)
<T> java.util.Map<T,java.lang.Long> incrementAll(java.util.Collection<T> keys, long delta)
<T> java.util.Map<T,java.lang.Long> incrementAll(java.util.Collection<T> keys, long delta, java.lang.Long initialValue)
initialValue
- value to insert into the cache if the key is not
present
<T> java.util.Map<T,java.lang.Long> incrementAll(java.util.Map<T,java.lang.Long> offsets)
<T> java.util.Map<T,java.lang.Long> incrementAll(java.util.Map<T,java.lang.Long> offsets, java.lang.Long initialValue)
void clearAll()