|
|||||||||
| 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 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. |
|
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). |
|
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. Since
null might be the set value in some cases, so we also have
contains(Object) which returns boolean.
key - the key object used to store the cache entry
null
java.lang.IllegalArgumentException - if the key cannot be serialized.
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 the key cannot be serialized.
InvalidValueException - for any error in reconstituting 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 and @{link get. This is
a sounder pattern:
foo = memcache.get("key");
if (foo == null) {
if (memcache.contains("key")) {
// continue, assuming foo had the real value null
} else {
// continue; foo may have had a real null, but has been dropped now
}
}
Another alternative is to prefer getAll(Collection), although
it requires making an otherwise-unneeded Collection of some sort.
key - the key object used to store the cache entry
true if the cache contains an entry for the key
java.lang.IllegalArgumentException - if the key cannot be serialized<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 an element of keys cannot be
used as a cache key. They should be Serializable.
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 the key or value type can't
be stored as a cache item. They should be Serializable.
MemcacheServiceException - if server responds with an error.
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 the key or value type can't
be stored as a cache item. They should be Serializable.
MemcacheServiceException - if server responds with an error.
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 the key or value type can't
be stored as a cache item. They should be Serializable.
MemcacheServiceException - if server respond with an error.
<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 the key or value type can't
be stored as a cache item. They should be Serializable.
MemcacheServiceException - if server respond 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 the key or value type can't be stored.
They should be Serializable. Also throws IllegalArgumentException
if oldValue is null.
MemcacheServiceException - if server respond with an error.
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 the key or value type can't be stored.
They should be Serializable. Also throws IllegalArgumentException
if oldValue is null.
MemcacheServiceException - if server respond with an error.
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 the key or value type can't
be stored as a cache item. They should be Serializable.
MemcacheServiceException - if server respond 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 the key or value type can't
be stored as a cache item. They should be Serializable.
MemcacheServiceException - if server respond with an error for any
of the given valuesboolean 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 the key can't be used in the cache
because it is not Serializable.
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 the key can't be used in the cache
because it is not Serializable.<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 a key can't be used in the cache
because it is not Serializable.
<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 the key can't be used in the cache
because it is not Serializable.
java.lang.Long increment(java.lang.Object key,
long delta)
Byte, Short, Integer,
Long, and in some cases String (if the string is parseable
as a number, for example via Long.parseLong(String). The entry must
already exist, and have a non-negative value.
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. However, due to the way
numbers are stored, decrementing -3 by -5 will result in
-8; so the zero-floor rule only applies to decrementing numbers
that were positive.
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, including wrapping beyond
signed 64-bit int max. However, if you get(Object) the key past
the point of wrapping, you will receive an unsigned integer value,
not a signed integer 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 the key can't be used in the cache
because it is not Serializable.
InvalidValueException - if the object incremented is not of a
integral type
java.lang.Long increment(java.lang.Object key,
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.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()
clearAll() does not respect
namespaces - this flushes the cache for every namespace.
Stats getStatistics()
getStatistics() does
not respect namespaces - this will return stats for every namespace. The
response will never be null.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||