MemcacheService (Google App Engine API for Java)

com.google.appengine.api.memcache

Interface MemcacheService

    • Method Detail

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

        If an error deserializing the value occurs, this passes an InvalidValueException to the service's ErrorHandler. If a service error occurs, this passes a MemcacheServiceException. See BaseMemcacheService.setErrorHandler(ErrorHandler).

        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

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

        If an error deserializing the value occurs, this passes an InvalidValueException to the service's ErrorHandler. If a service error occurs, this passes a MemcacheServiceException. See BaseMemcacheService.setErrorHandler(ErrorHandler).

        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

      • 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 and a ConsistentErrorHandler is not configured

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

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

        If a service error occurs, this passes a MemcacheServiceException to the service's ErrorHandler. See BaseMemcacheService.setErrorHandler(ErrorHandler).

        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 or holding a negative value

      • 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
        See Also:
        increment(Object, long)

      • 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
        See Also:
        increment(Object, long)

      • 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
        See Also:
        increment(Object, long)

      • 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
        See Also:
        increment(Object, long)

      • clearAll

        void clearAll()
        Empties the cache of all values across all namespaces. Statistics are not affected.

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