# MemcacheService
Date: 2012-02-24

## 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 `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.

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.

`

`<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)`
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)`.

`

`<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.

Methods inherited from interface com.google.appengine.api.memcache.BaseMemcacheService
`getErrorHandler, getNamespace, setErrorHandler`

Method Detail

### setNamespace

    @Deprecated
    void setNamespace(java.lang.String newNamespace)

  Deprecated. use `MemcacheServiceFactory.getMemcacheService(String)` instead.

### get

    java.lang.Object get(java.lang.Object key)

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

  Parameters:
    `key` - the key object used to store the cache entry
  Returns:
    the value object previously stored, or `null`
  Throws:
    `java.lang.IllegalArgumentException` - if `key` is not `Serializable` and is not `null`
    `InvalidValueException` - for any error in reconstituting the cache value.

### getIdentifiable

    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.

  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:
    `java.lang.IllegalArgumentException` - if `key` is not `Serializable` and is not `null`
    `InvalidValueException` - for any error in reconstituting the cache value

### 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 to `getIdentifiable(Object)`.

  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 of `keys` is not `Serializable` and is not `null`
    `InvalidValueException` - for any error in deserializing the cache value

### contains

    boolean contains(java.lang.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:
    `java.lang.IllegalArgumentException` - if `key` is not `Serializable` and is not `null`

### 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 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.

  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 of `keys` is not `Serializable` and is not `null`
    `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, 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:
    `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

### put

    void put(java.lang.Object key,
             java.lang.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:
    `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

### put

    void put(java.lang.Object key,
             java.lang.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:
    `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

### putAll

    <T> java.util.Set<T> 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)`. 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:
    `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

### putAll

    void putAll(java.util.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:
    `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

### putAll

    void putAll(java.util.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:
    `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

### putIfUntouched

    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. `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:
    `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

### putIfUntouched

    boolean putIfUntouched(java.lang.Object key,
                           MemcacheService.IdentifiableValue oldValue,
                           java.lang.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:
    `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

### putIfUntouched

    <T> java.util.Set<T> putIfUntouched(java.util.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:
    `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

### putIfUntouched

    <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)`. 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:
    `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

### delete

    boolean delete(java.lang.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:
    `java.lang.IllegalArgumentException` - if `key` is not `Serializable` and is not `null`

### delete

    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. 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:
    `java.lang.IllegalArgumentException` - if `key` is not `Serializable` and is not `null`

### deleteAll

    <T> java.util.Set<T> deleteAll(java.util.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:
    `java.lang.IllegalArgumentException` - if any element of `keys` is not `Serializable` and is not `null`

### deleteAll

    <T> java.util.Set<T> deleteAll(java.util.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:
    `java.lang.IllegalArgumentException` - if any element of `keys` is not `Serializable` and is not `null`

### increment

    java.lang.Long increment(java.lang.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.

  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:
    `java.lang.IllegalArgumentException` - if `key` is not `Serializable` and is not `null`
    `InvalidValueException` - if the object incremented is not of a integral type

### 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

### 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

### 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

### 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

### clearAll

    void clearAll()

  Empties the cache of all values. Statistics are not affected. Note that this method flushes the cache for all namespaces.

### 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`.