注意：在未来的几个月内，我们将会重新整理 App Engine 文档网站，使得查找内容更轻松，并更好地与其他 Google Cloud 产品保持一致。将会提供相同的内容，但导航现在将与其余的 Cloud 产品相一致。 如果您在浏览网站时有疑问或者希望提交反馈，请点击“发送反馈”。

MemcacheService（Java 版 Google App Engine API）

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。
com.google.appengine.api.memcache

MemcacheService 接口

    • 方法详细信息

      • contains

        boolean contains(java.lang.Object key)
        测试给定值是否位于缓存中，即使其值为 null。

        请注意，由于可能会随时从缓存中删除对象，因此，以下内容并不是完善的代码：

           if (memcache.contains("key")) {
     foo = memcache.get("key");
     if (foo == null) {
       // continue, assuming foo had the real value null
     }
   }
        问题在于，在调用 contains(java.lang.Object) 和 get(Object) 之间，缓存可能已丢弃该条目。下面是一个更完善的模式：
           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
     }
   }
        另一种方法是首选 getAll(Collection)，但它需要某种不需要的 Collection。

        参数：
        key - 用于存储缓存条目的键对象
        返回：
        true - 如果缓存包含键的条目
        抛出：
        java.lang.IllegalArgumentException - 如果 key 不是 Serializable 且不是 null

      • getAll

        <T> java.util.Map<T,java.lang.Object> getAll(java.util.Collection<T> keys)
        同时获取多个键。 这比多次单独调用 get(Object) 效率高，并且允许单次调用来测试 contains(Object) 并提取值，因为返回将不包含找不到的键的映射。

        如果反序列化该值时发生错误，则会将 InvalidValueException 传递给服务的 ErrorHandler。如果发生服务错误，则传递 MemcacheServiceException。请参阅 BaseMemcacheService.setErrorHandler(ErrorHandler)。

        参数：
        keys - 应检索其值的键集合
        返回：
        找到的任何条目的键和值之间的映射。 如果在缓存中找不到请求的键，则返回的 Map 中不包括该键。
        抛出：
        java.lang.IllegalArgumentException - 如果 keys 的任何元素不是 Serializable 且不是 null
        InvalidValueException - 对于在缓存值进行反序列化时出现的任何错误

      • put

        boolean put(java.lang.Object key,
            java.lang.Object value,
            Expiration expires,
            MemcacheService.SetPolicy policy)
        使用 key 将新值存储到缓存中，但遵守有关现有条目的 policy。
        参数：
        key - 新缓存条目的键
        value - 要存储的值
        expires - Expiration 对象，用于设置基于时间的到期时间。null 可用于指示没有具体到期时间。
        policy - 请求处理同一键下预先存在的条目。此参数不能是 null。
        返回：
        如果创建了新条目，则为 true；如果没有，则为 false（由于 policy 的缘故）
        抛出：
        java.lang.IllegalArgumentException - 如果 key 或 value 不是 Serializable 且不是 null
        MemcacheServiceException - 如果服务器返回错误，并且未配置 ConsistentErrorHandler

      • putAll

        void putAll(java.util.Map<?,?> values,
            Expiration expires)
        简便的多重放置，相当于 putAll(values, expires, SetPolicy.SET_ALWAYS)。
        参数：
        values - 要添加到缓存中的键/值映射
        expires - 新值的到期时间，或 null（表示没有基于时间的到期时间）
        抛出：
        java.lang.IllegalArgumentException - 如果任何键或值不是 Serializable 且不是 null
        MemcacheServiceException - 如果服务器返回任何给定值的错误，并且未配置 ConsistentErrorHandler

      • putIfUntouched

        boolean putIfUntouched(java.lang.Object key,
                       MemcacheService.IdentifiableValue oldValue,
                       java.lang.Object newValue)
        简便的快捷方式，相当于 put(key, oldValue, newValue, null)。
        参数：
        key - 条目的键
        oldValue - 要与 newValue 进行比较的值的标识符
        newValue - 当 oldValue 仍然存在时要存储的新值
        返回：
        如果 newValue 已存储则为 true，否则为 false。
        抛出：
        java.lang.IllegalArgumentException - 如果 key 或 newValue 不是 Serializable，也不是 null。此外，如果 oldValue 是 null，则会抛出 IllegalArgumentException。
        MemcacheServiceException - 如果服务器返回错误，并且未配置 ConsistentErrorHandler

      • putIfUntouched

        <T> java.util.Set<T> putIfUntouched(java.util.Map<T,MemcacheService.CasValues> values)
        简便的快捷方式，相当于 putIfUntouched(values, null)。
        参数：
        values - 要比较和交换的键/值对映射
        返回：
        存储新值的键集。
        抛出：
        java.lang.IllegalArgumentException - 如果任何键不是 Serializable 或任何值不是 Serializable 或 null
        java.lang.IllegalArgumentException - 如果任何键或 newValues 不是 Serializable，也不是 null。如果 values 具有任何 null，则也会抛出 IllegalArgumentException。
        MemcacheServiceException - 如果服务器针对任何给定 values 返回错误并且未配置 ConsistentErrorHandler

      • delete

        boolean delete(java.lang.Object key)
        从缓存中移除 key。
        参数：
        key - 要删除的条目的键。
        返回：
        true（如果条目存在但已被舍弃）
        抛出：
        java.lang.IllegalArgumentException - 如果 key 不是 Serializable 且不是 null

      • deleteAll

        <T> java.util.Set<T> deleteAll(java.util.Collection<T> keys)
        delete(Object) 的批处理版本。
        参数：
        keys - 要删除的条目的键集合
        返回：
        删除的键的集合。存在于 keys 中但是不存于于返回的集中的任何键在缓存中找不到。返回集的迭代顺序与提供的 keys 的迭代顺序匹配。
        抛出：
        java.lang.IllegalArgumentException - 如果 keys 的任何元素不是 Serializable 且不是 null

      • deleteAll

        <T> java.util.Set<T> deleteAll(java.util.Collection<T> keys,
                               long millisNoReAdd)
        delete(Object, long) 的批处理版本。
        参数：
        keys - 要删除的条目的键集合
        millisNoReAdd - 一个时间，在此时间内，应拒绝那些使用 MemcacheService.SetPolicy.ADD_ONLY_IF_NOT_PRESENT 进行的调用。
        返回：
        删除的键的集合。存在于 keys 中但是不存于于返回的集中的任何键在缓存中找不到。返回集的迭代顺序与提供的 keys 的迭代顺序匹配。
        抛出：
        java.lang.IllegalArgumentException - 如果 keys 的任何元素不是 Serializable 且不是 null

      • increment

        java.lang.Long increment(java.lang.Object key,
                         long delta)
        以原子方式提取、增加和存储给定的整数值。 “整数”类型为 Byte、Short、Integer、Long，在某些情况下为 String。条目必须已存在，并且值不是负数。

        按正值递增将达到有符号的 64 位最大值 (2^63 - 1)，然后返回到有符号的 64 位最小值 (-2^63)，并从该位置继续递增。

        为了方便使用原子倒计时，按负值递增（即，递减）不会小于零：如果将 2 增加 -5，则返回 0 而不是 -3。

        注意：内存缓存中的所有数字的实际表示形式为字符串。 这意味着您最初将数字存储为字符串（例如，“10”），然后递增它，则一切正常。

        当您为字符串值 get(Object) 键时，会在超出无符号 64 位数的最大值 (2^64 - 1) 的最大值后进行封装。当您为数值类型 get(Object) 键时，会在超出类型最大值后进行封装。

        如果发生服务错误，这会将 MemcacheServiceException 传递给服务的 ErrorHandler。请参阅 BaseMemcacheService.setErrorHandler(ErrorHandler)。

        参数：
        key - 要操作的条目的键
        delta - 增量的大小（正数或负数）
        返回：
        长整型正增量值。但是，键的 get(Object) 仍将具有原来的类型（Byte、Short 等）。如果 key 没有条目，则返回 null。
        抛出：
        java.lang.IllegalArgumentException - 如果 key 不是 Serializable，也不是 null
        InvalidValueException - 如果对象递增不是整数类型或包含负值

      • incrementAll

        <T> java.util.Map<T,java.lang.Long> incrementAll(java.util.Collection<T> keys,
                                                 long delta)
        与正常增加类似，但使用相同的增量并行增加一批单独的键。
        返回：
        将键映射到其新值；如果无法增加这些值，或这些值在缓存中不存在，则值为 null
        另请参阅：
        increment(Object, long)

      • incrementAll

        <T> java.util.Map<T,java.lang.Long> incrementAll(java.util.Collection<T> keys,
                                                 long delta,
                                                 java.lang.Long initialValue)
        与正常增加类似，但使用相同的增量并行增加一批单独的键，并且可能会设置起始值。
        参数：
        initialValue - 要在键不存在时插入到缓存中的值
        返回：
        将键映射到其新值；如果由于任何原因而无法增加这些值，则这些值为 null
        另请参阅：
        increment(Object, long)

      • incrementAll

        <T> java.util.Map<T,java.lang.Long> incrementAll(java.util.Map<T,java.lang.Long> offsets)
        与正常增加类似，但接受分别为每个键映射单独的可控制偏移。非常适于按总和及计数并行增加。
        返回：
        将键映射到其新值；如果由于任何原因而无法增加这些值，则这些值为 null
        另请参阅：
        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)
        与正常增加类似，但接受分别为每个键映射单独的可控制偏移。非常适于按总和及计数并行增加。如果键使用的初始值在缓存中不存在，调用者也可以传递这些值。
        返回：
        将键映射到其新值；如果由于任何原因而无法增加这些值，则这些值为 null
        另请参阅：
        increment(Object, long)

      • clearAll

        void clearAll()
        清空所有命名空间中所有值的缓存。统计信息不受影响。

      • getStatistics

        Stats getStatistics()
        提取一些有关缓存及其使用情况的统计信息。
        返回：
        缓存的统计信息。请注意，此方法会返回所有命名空间的聚合 Stats。响应永远不会为 null。