Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.appengine.api.memcache
Interface MemcacheService

    public interface MemcacheService

The Java API for the App Engine Memcache service. This offers a fast distrubted 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.

Except for the `increment(java.lang.Object, long)` method, this service does not offer atomicity guarantees. In particular, the multi-key `getAll(java.util.Collection)`, `putAll(java.util.Map, com.google.appengine.api.memcache.Expiration, com.google.appengine.api.memcache.MemcacheService.SetPolicy)`, and `deleteAll(java.util.Collection)` operations are non-atomic.

`Increment` has a number of caveats to its use; please consult the method documentation.

Nested Class Summary
`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.
`java.util.Set<java.lang.Object>` | `deleteAll(java.util.Collection<java.lang.Object> keys)` Batch version of `delete(Object)`.
`java.util.Set<java.lang.Object>` | `deleteAll(java.util.Collection<java.lang.Object> 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.
`java.util.Map<java.lang.Object,java.lang.Object>` | `getAll(java.util.Collection<java.lang.Object> keys)` Performs a get of multiple keys at once.
`ErrorHandler` | `getErrorHandler()` Fetches the current error handler.
`java.lang.String` | `getNamespace()` Get the name of the namespace that will be used in API calls.
`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.
`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<java.lang.Object,java.lang.Object> values)` Convenience multi-put, equivalent to `putAll(values, expires, SetPolicy.SET_ALWAYS)`.
`void` | `putAll(java.util.Map<java.lang.Object,java.lang.Object> values, Expiration expires)` Convenience multi-put, equivalent to `putAll(values, expires, SetPolicy.SET_ALWAYS)`.
`java.util.Set<java.lang.Object>` | `putAll(java.util.Map<java.lang.Object,java.lang.Object> 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)`.
`void` | `setErrorHandler(ErrorHandler handler)` Registers a new `ErrorHandler`.
`void` | `setNamespace(java.lang.String newNamespace)` Change the namespace used in API calls.

Method Detail

### getNamespace

    java.lang.String getNamespace()

  Get the name of the namespace that will be used in API calls. This is initially set based on `NamespaceManager.get()`.

### setNamespace

    void setNamespace(java.lang.String newNamespace)

  Change the namespace used in API calls.

  Parameters:
    `newNamespace` - the new namespace to use. If `null`, switch back to the default namespace, as specified by `NamespaceManager.get()`.

### get

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

  Fetches a previously-stored value, or `null` if unset. Since `null` might be the set value in some cases, so we also have `contains(Object)` which returns `boolean`.

  Parameters:
    `key` - the key object used to store the cache entry
  Returns:
    the value object previously stored, or `null`
  Throws:
    `java.lang.IllegalArgumentException` - if the type of the key cannot be supported.
    `InvalidValueException` - for any error in reconstituting 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` 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.

  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 the key cannot be serialized

### getAll

    java.util.Map<java.lang.Object,java.lang.Object> getAll(java.util.Collection<java.lang.Object> 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 an element of `keys` cannot be used as a cache key. They should be `Serializable`.
    `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 the key or value type can't be stored as a cache item. They should be `Serializable`.

### 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 the key or value type can't be stored as a cache item. They should be `Serializable`.

### 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 the key or value type can't be stored as a cache item. They should be `Serializable`.

### putAll

    java.util.Set<java.lang.Object> putAll(java.util.Map<java.lang.Object,java.lang.Object> 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 the key or value type can't be stored as a cache item. They should be `Serializable`.

### putAll

    void putAll(java.util.Map<java.lang.Object,java.lang.Object> 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 the key or value type can't be stored as a cache item. They should be `Serializable`.

### putAll

    void putAll(java.util.Map<java.lang.Object,java.lang.Object> 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 the key or value type can't be stored as a cache item. They should be `Serializable`.

### 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 the key can't be used in the cache because it is not `Serializable`.

### 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 the key can't be used in the cache because it is not `Serializable`.

### deleteAll

    java.util.Set<java.lang.Object> deleteAll(java.util.Collection<java.lang.Object> 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.
  Throws:
    `java.lang.IllegalArgumentException` - if a key can't be used in the cache because it is not `Serializable`.

### deleteAll

    java.util.Set<java.lang.Object> deleteAll(java.util.Collection<java.lang.Object> keys,
                                              long millisNoReAdd)

  Batch version of `delete(Object, long)`.

  Parameters:
    `keys` - the keys to be deleted
    `millisNoReAdd` - time during which calls to put using `MemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT` should be denied.
  Returns:
    the set of keys deleted.
  Throws:
    `java.lang.IllegalArgumentException` - if the key can't be used in the cache because it is not `Serializable`.

### 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` (if the string is parseable as a number, for example via `Long.parseLong(String)`. The entry must already exist.

  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(java.lang.Object)` of the key will still have the original type (`Byte`, `Short`, etc.). For example, if the value is a `Byte` with value 126, the return from incrementing by 10 will be `(long) 136`, but the subsequent return from `get(java.lang.Object)` will be a `Byte` of -122. If there is no entry for `key`, returns `null`.
  Throws:
    `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

### clearAll

    void clearAll()

  Empties the cache of all values. Statistics are not affected. Note that `clearAll()` does not respect namespaces - this flushes the cache for every namespace.

### getStatistics

    Stats getStatistics()

  Fetches some statistics about the cache and its usage.

  Returns:
    statistics for the cache. May be `null`, to indicate that server statistics are not available. Note that `getStatistics()` does not respect namespaces - this will return stats for every namespace.

### setErrorHandler

    void setErrorHandler(ErrorHandler handler)

  Registers a new `ErrorHandler`. The `handler` is used to field any errors which aren't necessarily the application programmer's fault: things like network timeouts, for example. Value correctness and usage errors `IllegalArgumentException`, `InvalidValueException` are still thrown normally.

  Parameters:
    `handler` - the new `ErrorHandler` to use. May not be `null`; use `ErrorHandler#LOGGING_ERROR_HANDLER` to explicitly restore default behavior.

### getErrorHandler

    ErrorHandler getErrorHandler()

  Fetches the current error handler.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD