Class LayeredCache<K,V>

java.lang.Object
cloud.opencode.base.cache.LayeredCache<K,V>
Type Parameters:
K - the type of keys | 键类型
V - the type of values | 值类型
All Implemented Interfaces:
Cache<K,V>
@Deprecated(since="1.0.3", forRemoval=true) public class LayeredCache<K,V> extends Object implements Cache<K,V>
Deprecated, for removal: This API element is subject to removal in a future version.
Use MultiLevelCache instead. This class will be removed in a future version. 已废弃，请使用 MultiLevelCache 替代。 此类将在未来版本中移除。
LayeredCache - Multi-level cache implementation (L1/L2) 分层缓存 - 多级缓存实现 (L1/L2)

Implements a two-level cache strategy where L1 (fast, smaller) is checked first, then L2 (slower, larger) if not found. Write-through or write-back strategies can be configured.

实现两级缓存策略，首先检查 L1（快速、较小），如果未找到则检查 L2（较慢、较大）。 可配置写穿或写回策略。

Features | 主要功能:

  • L1 (local) + L2 (shared) caching - L1（本地）+ L2（共享）缓存
  • Write-through strategy - 写穿策略
  • Write-back strategy - 写回策略
  • Automatic L1 population on L2 hit - L2命中时自动填充L1
  • Configurable promotion policies - 可配置的提升策略

Usage Examples | 使用示例:

// Create layered cache - 创建分层缓存
Cache<String, User> l1 = OpenCache.<String, User>builder()
    .maxSize(1000)
    .expireAfterWrite(Duration.ofMinutes(5))
    .build("l1-users");

Cache<String, User> l2 = OpenCache.<String, User>builder()
    .maxSize(10000)
    .expireAfterWrite(Duration.ofHours(1))
    .build("l2-users");

LayeredCache<String, User> cache = LayeredCache.of(l1, l2);

// Get - checks L1, then L2, promotes to L1 if found in L2
User user = cache.get("user:1001");

// Put - writes to both L1 and L2
cache.put("user:1001", user);

Performance | 性能特性:

  • L1 hit: O(1) - L1命中: O(1)
  • L2 hit: O(1) + promotion cost - L2命中: O(1) + 提升成本
  • Miss: L1 miss + L2 miss + optional load - 未命中: L1未命中 + L2未命中 + 可选加载

Security | 安全性:

  • Thread-safe: Yes - 线程安全: 是
  • Null-safe: Partial (null values not allowed) - 空值安全: 部分（不允许null值）
Since:
JDK 25, opencode-base-cache V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    LayeredCache.Builder<K,V>
    Deprecated, for removal: This API element is subject to removal in a future version.
    Builder for LayeredCache LayeredCache构建器
    static final record 
    LayeredCache.LayeredCacheStats
    Deprecated, for removal: This API element is subject to removal in a future version.
    Layered cache statistics 分层缓存统计
    static enum 
    LayeredCache.WriteStrategy
    Deprecated, for removal: This API element is subject to removal in a future version.
    Write strategy for layered cache 分层缓存的写策略

  • Method Summary

    Modifier and Type
    Method
    Description
    ConcurrentMap<K,V>
    asMap()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get a concurrent map view of this cache 获取 ConcurrentMap 视图
    AsyncCache<K,V>
    async()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get async view of this cache 获取异步视图
    static <K,V> LayeredCache.Builder<K,V>
    builder(Cache<K,V> l1, Cache<K,V> l2)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Creates a builder for layered cache 创建分层缓存构建器
    void
    cleanUp()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Perform cleanup (expired entries, etc.)
    boolean
    containsKey(K key)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Check if key exists 检查键是否存在
    Set<Map.Entry<K,V>>
    entries()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get snapshot of all entries 获取所有条目的快照
    long
    estimatedSize()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get estimated entry count (fast) 获取估算条目数（快速）
    void
    flush()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Flushes L1 to L2 (for write-back strategy) 将L1刷新到L2（用于写回策略）
    V
    get(K key)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get value by key, returns null if not present 根据键获取值，不存在返回 null
    V
    get(K key, Function<? super K, ? extends V> loader)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get value by key, load using loader if not present 根据键获取值，不存在时通过 loader 加载
    Map<K,V>
    getAll(Iterable<? extends K> keys)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get all values for given keys, returns only existing entries 批量获取，仅返回存在的条目
    Map<K,V>
    getAll(Iterable<? extends K> keys, Function<? super Set<? extends K>, ? extends Map<K,V>> loader)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get all values, load missing keys using loader 批量获取，缺失的键通过 loader 加载
    void
    invalidate(K key)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Invalidate a single key 使单个键失效
    void
    invalidateAll()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Invalidate all entries 清空所有缓存
    void
    invalidateAll(Iterable<? extends K> keys)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Invalidate multiple keys 批量失效
    boolean
    isPromoteOnL2Hit()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Checks if promotion on L2 hit is enabled 检查是否启用L2命中时提升
    Set<K>
    keys()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get snapshot of all keys 获取所有键的快照
    Cache<K,V>
    l1()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Gets the L1 cache 获取L1缓存
    Cache<K,V>
    l2()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Gets the L2 cache 获取L2缓存
    LayeredCache.LayeredCacheStats
    layeredStats()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Gets combined statistics for both layers 获取两层的组合统计信息
    String
    name()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get cache name 获取缓存名称
    static <K,V> LayeredCache<K,V>
    of(Cache<K,V> l1, Cache<K,V> l2)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Creates a layered cache with default settings 使用默认设置创建分层缓存
    void
    put(K key, V value)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Put a key-value pair into cache 放入键值对
    void
    putAll(Map<? extends K, ? extends V> map)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Put all key-value pairs into cache 批量放入
    void
    putAllWithTtl(Map<? extends K, ? extends V> map, Duration ttl)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Put all entries with custom TTL 批量放入并指定自定义 TTL
    boolean
    putIfAbsent(K key, V value)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Put if the key is absent, returns true if successful 不存在时放入，成功返回 true
    boolean
    putIfAbsentWithTtl(K key, V value, Duration ttl)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Put if absent with custom TTL 不存在时放入并指定自定义 TTL
    void
    putWithTtl(K key, V value, Duration ttl)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Put a key-value pair with custom TTL (overrides default expiration) 放入键值对并指定自定义 TTL（覆盖默认过期时间）
    long
    size()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get exact entry count (may be slow) 获取精确条目数（可能较慢）
    CacheStats
    stats()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get cache statistics 获取缓存统计信息
    Collection<V>
    values()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get snapshot of all values 获取所有值的快照
    void
    warmUp(Iterable<? extends K> keys)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Warms up L1 from L2 with specified keys 使用指定键从L2预热L1
    LayeredCache.WriteStrategy
    writeStrategy()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Gets the write strategy 获取写策略

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface Cache

    clear, compute, computeIfAbsent, computeIfMatch, computeIfPresent, containsValue, entryIterator, entryParallelStream, entryStream, forEach, forEachKey, forEachValue, getAndRemove, getByPattern, getIfPresent, getOptional, getOrDefault, getOrNull, invalidateByPattern, invalidateByValue, invalidateIf, isEmpty, keyIterator, keyParallelStream, keyStream, merge, metrics, putAllIfAbsent, putIfPresent, removeIfEquals, removeIfPresent, replace, replace, replaceAll, replaceIf, resetStats, updateAll, updateTtl, updateTtl, updateTtlAll, valueParallelStream, valueStream

  • Method Details

    • of

      public static <K,V> LayeredCache<K,V> of(Cache<K,V> l1, Cache<K,V> l2)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Creates a layered cache with default settings 使用默认设置创建分层缓存
      Type Parameters:
      K - key type | 键类型
      V - value type | 值类型
      Parameters:
      l1 - L1 cache (fast, small) | L1缓存（快速、小）
      l2 - L2 cache (slower, large) | L2缓存（较慢、大）
      Returns:
      layered cache | 分层缓存

    • builder

      public static <K,V> LayeredCache.Builder<K,V> builder(Cache<K,V> l1, Cache<K,V> l2)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Creates a builder for layered cache 创建分层缓存构建器
      Type Parameters:
      K - key type | 键类型
      V - value type | 值类型
      Parameters:
      l1 - L1 cache | L1缓存
      l2 - L2 cache | L2缓存
      Returns:
      builder | 构建器

    • get

      public V get(K key)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get value by key, returns null if not present 根据键获取值，不存在返回 null
      Specified by:
      get in interface Cache<K,V>
      Parameters:
      key - the key | 键
      Returns:
      the value or null | 值或 null

    • get

      public V get(K key, Function<? super K, ? extends V> loader)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get value by key, load using loader if not present 根据键获取值，不存在时通过 loader 加载
      Specified by:
      get in interface Cache<K,V>
      Parameters:
      key - the key | 键
      loader - the loader function | 加载函数
      Returns:
      the value | 值

    • getAll

      public Map<K,V> getAll(Iterable<? extends K> keys)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get all values for given keys, returns only existing entries 批量获取，仅返回存在的条目
      Specified by:
      getAll in interface Cache<K,V>
      Parameters:
      keys - the keys | 键集合
      Returns:
      map of existing entries | 存在的条目 Map

    • getAll

      public Map<K,V> getAll(Iterable<? extends K> keys, Function<? super Set<? extends K>, ? extends Map<K,V>> loader)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get all values, load missing keys using loader 批量获取，缺失的键通过 loader 加载
      Specified by:
      getAll in interface Cache<K,V>
      Parameters:
      keys - the keys | 键集合
      loader - the batch loader function | 批量加载函数
      Returns:
      map of all entries | 所有条目 Map

    • put

      public void put(K key, V value)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Put a key-value pair into cache 放入键值对
      Specified by:
      put in interface Cache<K,V>
      Parameters:
      key - the key | 键
      value - the value | 值

    • putAll

      public void putAll(Map<? extends K, ? extends V> map)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Put all key-value pairs into cache 批量放入
      Specified by:
      putAll in interface Cache<K,V>
      Parameters:
      map - the key-value pairs | 键值对 Map

    • putIfAbsent

      public boolean putIfAbsent(K key, V value)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Put if the key is absent, returns true if successful 不存在时放入，成功返回 true
      Specified by:
      putIfAbsent in interface Cache<K,V>
      Parameters:
      key - the key | 键
      value - the value | 值
      Returns:
      true if put successfully | 成功放入返回 true

    • putWithTtl

      public void putWithTtl(K key, V value, Duration ttl)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Put a key-value pair with custom TTL (overrides default expiration) 放入键值对并指定自定义 TTL（覆盖默认过期时间）
      Specified by:
      putWithTtl in interface Cache<K,V>
      Parameters:
      key - the key | 键
      value - the value | 值
      ttl - the time-to-live for this entry | 此条目的存活时间

    • putAllWithTtl

      public void putAllWithTtl(Map<? extends K, ? extends V> map, Duration ttl)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Put all entries with custom TTL 批量放入并指定自定义 TTL
      Specified by:
      putAllWithTtl in interface Cache<K,V>
      Parameters:
      map - the key-value pairs | 键值对 Map
      ttl - the time-to-live for all entries | 所有条目的存活时间

    • putIfAbsentWithTtl

      public boolean putIfAbsentWithTtl(K key, V value, Duration ttl)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Put if absent with custom TTL 不存在时放入并指定自定义 TTL
      Specified by:
      putIfAbsentWithTtl in interface Cache<K,V>
      Parameters:
      key - the key | 键
      value - the value | 值
      ttl - the time-to-live | 存活时间
      Returns:
      true if put successfully | 成功放入返回 true

    • invalidate

      public void invalidate(K key)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Invalidate a single key 使单个键失效
      Specified by:
      invalidate in interface Cache<K,V>
      Parameters:
      key - the key to invalidate | 要失效的键

    • invalidateAll

      public void invalidateAll(Iterable<? extends K> keys)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Invalidate multiple keys 批量失效
      Specified by:
      invalidateAll in interface Cache<K,V>
      Parameters:
      keys - the keys to invalidate | 要失效的键集合

    • invalidateAll

      public void invalidateAll()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Invalidate all entries 清空所有缓存
      Specified by:
      invalidateAll in interface Cache<K,V>

    • containsKey

      public boolean containsKey(K key)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Check if key exists 检查键是否存在
      Specified by:
      containsKey in interface Cache<K,V>
      Parameters:
      key - the key | 键
      Returns:
      true if exists | 存在返回 true

    • size

      public long size()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get exact entry count (may be slow) 获取精确条目数（可能较慢）
      Specified by:
      size in interface Cache<K,V>
      Returns:
      entry count | 条目数

    • estimatedSize

      public long estimatedSize()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get estimated entry count (fast) 获取估算条目数（快速）
      Specified by:
      estimatedSize in interface Cache<K,V>
      Returns:
      estimated count | 估算数量

    • keys

      public Set<K> keys()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get snapshot of all keys 获取所有键的快照
      Specified by:
      keys in interface Cache<K,V>
      Returns:
      set of keys | 键集合

    • values

      public Collection<V> values()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get snapshot of all values 获取所有值的快照
      Specified by:
      values in interface Cache<K,V>
      Returns:
      collection of values | 值集合

    • entries

      public Set<Map.Entry<K,V>> entries()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get snapshot of all entries 获取所有条目的快照
      Specified by:
      entries in interface Cache<K,V>
      Returns:
      set of entries | 条目集合

    • asMap

      public ConcurrentMap<K,V> asMap()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get a concurrent map view of this cache 获取 ConcurrentMap 视图
      Specified by:
      asMap in interface Cache<K,V>
      Returns:
      concurrent map view | ConcurrentMap 视图

    • stats

      public CacheStats stats()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get cache statistics 获取缓存统计信息
      Specified by:
      stats in interface Cache<K,V>
      Returns:
      cache statistics | 缓存统计

    • cleanUp

      public void cleanUp()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Perform cleanup (expired entries, etc.) 执行清理（过期条目等）
      Specified by:
      cleanUp in interface Cache<K,V>

    • async

      public AsyncCache<K,V> async()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get async view of this cache 获取异步视图
      Specified by:
      async in interface Cache<K,V>
      Returns:
      async cache view | 异步缓存视图

    • name

      public String name()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Cache
      Get cache name 获取缓存名称
      Specified by:
      name in interface Cache<K,V>
      Returns:
      cache name | 缓存名称

    • l1

      public Cache<K,V> l1()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Gets the L1 cache 获取L1缓存
      Returns:
      L1 cache | L1缓存

    • l2

      public Cache<K,V> l2()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Gets the L2 cache 获取L2缓存
      Returns:
      L2 cache | L2缓存

    • writeStrategy

      public LayeredCache.WriteStrategy writeStrategy()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Gets the write strategy 获取写策略
      Returns:
      write strategy | 写策略

    • isPromoteOnL2Hit

      public boolean isPromoteOnL2Hit()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Checks if promotion on L2 hit is enabled 检查是否启用L2命中时提升
      Returns:
      true if enabled | 如果启用则为true

    • flush

      public void flush()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Flushes L1 to L2 (for write-back strategy) 将L1刷新到L2（用于写回策略）
      Throws:
      RuntimeException - if flush fails | 刷新失败时抛出运行时异常

    • warmUp

      public void warmUp(Iterable<? extends K> keys)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Warms up L1 from L2 with specified keys 使用指定键从L2预热L1
      Parameters:
      keys - keys to warm up | 要预热的键

    • layeredStats

      public LayeredCache.LayeredCacheStats layeredStats()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Gets combined statistics for both layers 获取两层的组合统计信息
      Returns:
      combined stats | 组合统计