|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface MemcacheService
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, putAll(java.util.Map, and
deleteAll(java.util.Collection 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.
| Nested Class Summary | |
|---|---|
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. |
| 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. |
|
|
deleteAll(java.util.Collection<T> keys)
Batch version of delete(Object). |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
incrementAll(java.util.Collection<T> keys,
long delta)
Like normal increment, but increments a batch of separate keys in parallel by the same delta. |
|
|
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. |
|
|
incrementAll(java.util.Map<T,java.lang.Long> offsets)
Like normal increment, but accepts a mapping of separate controllable offsets for each key individually. |
|
|
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). |
|
|
putAll(java.util.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). |
|
|
putIfUntouched(java.util.Map<T,MemcacheService.CasValues> values)
Convenience shortcut, equivalent to putIfUntouched(values, null). |
|
|
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. |
|
| Methods inherited from interface com.google.appengine.api.memcache.BaseMemcacheService |
|---|
getErrorHandler, getNamespace, setErrorHandler |
| Method Detail |
|---|
@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
valueboolean 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 entryvalue - the value to be storedexpires - 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 entryvalue - value for the new entryexpires - 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 entryvalue - 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 cacheexpires - 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 cacheexpires - 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 valuesvoid 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 entryoldValue - identifier for the value to compare against newValuenewValue - new value to store if oldValue is still thereexpires - 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 entryoldValue - identifier for the value to compare against newValuenewValue - 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 swapexpiration - 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
configuredboolean 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 deletemillisNoReAdd - 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 deletemillisNoReAdd - 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 manipulatedelta - 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
presentincrement(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()
Stats getStatistics()
Stats for all namespaces. Response will never be
null.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||