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>

public class LayeredCache<K,V> extends Object implements Cache<K,V>

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>

Builder for LayeredCache LayeredCache构建器

static final record

LayeredCache.LayeredCacheStats

Layered cache statistics 分层缓存统计

static enum

LayeredCache.WriteStrategy

Write strategy for layered cache 分层缓存的写策略
Method Summary

Modifier and Type

Method

Description

ConcurrentMap<K,V>

asMap()

Get a concurrent map view of this cache 获取 ConcurrentMap 视图

AsyncCache<K,V>

async()

Get async view of this cache 获取异步视图

static <K,V> LayeredCache.Builder<K,V>

builder(Cache<K,V> l1, Cache<K,V> l2)

Creates a builder for layered cache 创建分层缓存构建器

void

cleanUp()

Perform cleanup (expired entries, etc.)

boolean

containsKey(K key)

Check if key exists 检查键是否存在

Set<Map.Entry<K,V>>

entries()

Get snapshot of all entries 获取所有条目的快照

long

estimatedSize()

Get estimated entry count (fast) 获取估算条目数（快速）

void

flush()

Flushes L1 to L2 (for write-back strategy) 将L1刷新到L2（用于写回策略）

V

get(K key)

Get value by key, returns null if not present 根据键获取值，不存在返回 null

V

get(K key, Function<? super K, ? extends V> loader)

Get value by key, load using loader if not present 根据键获取值，不存在时通过 loader 加载

Map<K,V>

getAll(Iterable<? extends K> keys)

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)

Get all values, load missing keys using loader 批量获取，缺失的键通过 loader 加载

void

invalidate(K key)

Invalidate a single key 使单个键失效

void

invalidateAll()

Invalidate all entries 清空所有缓存

void

invalidateAll(Iterable<? extends K> keys)

Invalidate multiple keys 批量失效

boolean

isPromoteOnL2Hit()

Checks if promotion on L2 hit is enabled 检查是否启用L2命中时提升

Set<K>

keys()

Get snapshot of all keys 获取所有键的快照

Cache<K,V>

l1()

Gets the L1 cache 获取L1缓存

Cache<K,V>

l2()

Gets the L2 cache 获取L2缓存

LayeredCache.LayeredCacheStats

layeredStats()

Gets combined statistics for both layers 获取两层的组合统计信息

String

name()

Get cache name 获取缓存名称

static <K,V> LayeredCache<K,V>

of(Cache<K,V> l1, Cache<K,V> l2)

Creates a layered cache with default settings 使用默认设置创建分层缓存

void

put(K key, V value)

Put a key-value pair into cache 放入键值对

void

putAll(Map<? extends K, ? extends V> map)

Put all key-value pairs into cache 批量放入

void

putAllWithTtl(Map<? extends K, ? extends V> map, Duration ttl)

Put all entries with custom TTL 批量放入并指定自定义 TTL

boolean

putIfAbsent(K key, V value)

Put if the key is absent, returns true if successful 不存在时放入，成功返回 true

boolean

putIfAbsentWithTtl(K key, V value, Duration ttl)

Put if absent with custom TTL 不存在时放入并指定自定义 TTL

void

putWithTtl(K key, V value, Duration ttl)

Put a key-value pair with custom TTL (overrides default expiration) 放入键值对并指定自定义 TTL（覆盖默认过期时间）

long

size()

Get exact entry count (may be slow) 获取精确条目数（可能较慢）

CacheStats

stats()

Get cache statistics 获取缓存统计信息

Collection<V>

values()

Get snapshot of all values 获取所有值的快照

void

warmUp(Iterable<? extends K> keys)

Warms up L1 from L2 with specified keys 使用指定键从L2预热L1

LayeredCache.WriteStrategy

writeStrategy()

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, 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, 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)
  
  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)
  
  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)
  
  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)
  
  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)
  
  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)
  
  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)
  
  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)
  
  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)
  
  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)
  
  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)
  
  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)
  
  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)
  
  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)
  
  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()
  
  Description copied from interface: Cache
  
  Invalidate all entries 清空所有缓存
  
  Specified by:
  
  invalidateAll in interface Cache<K,V>
- containsKey
  
  public boolean containsKey(K key)
  
  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()
  
  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()
  
  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()
  
  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()
  
  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()
  
  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()
  
  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()
  
  Description copied from interface: Cache
  
  Get cache statistics 获取缓存统计信息
  
  Specified by:
  
  stats in interface Cache<K,V>
  
  Returns:
  
  cache statistics | 缓存统计
- cleanUp
  
  public void cleanUp()
  
  Description copied from interface: Cache
  
  Perform cleanup (expired entries, etc.) 执行清理（过期条目等）
  
  Specified by:
  
  cleanUp in interface Cache<K,V>
- async
  
  public AsyncCache<K,V> async()
  
  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()
  
  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()
  
  Gets the L1 cache 获取L1缓存
  
  Returns:
  
  L1 cache | L1缓存
- l2
  
  public Cache<K,V> l2()
  
  Gets the L2 cache 获取L2缓存
  
  Returns:
  
  L2 cache | L2缓存
- writeStrategy
  
  public LayeredCache.WriteStrategy writeStrategy()
  
  Gets the write strategy 获取写策略
  
  Returns:
  
  write strategy | 写策略
- isPromoteOnL2Hit
  
  public boolean isPromoteOnL2Hit()
  
  Checks if promotion on L2 hit is enabled 检查是否启用L2命中时提升
  
  Returns:
  
  true if enabled | 如果启用则为true
- flush
  
  public void flush()
  
  Flushes L1 to L2 (for write-back strategy) 将L1刷新到L2（用于写回策略）
  
  Throws:
  
  RuntimeException - if flush fails | 刷新失败时抛出运行时异常
- warmUp
  
  public void warmUp(Iterable<? extends K> keys)
  
  Warms up L1 from L2 with specified keys 使用指定键从L2预热L1
  
  Parameters:
  
  keys - keys to warm up | 要预热的键
- layeredStats
  
  public LayeredCache.LayeredCacheStats layeredStats()
  
  Gets combined statistics for both layers 获取两层的组合统计信息
  
  Returns:
  
  combined stats | 组合统计

Class LayeredCache<K,V>

Nested Class Summary

Method Summary

Methods inherited from class Object

Methods inherited from interface Cache

Method Details

of

builder

get

get

getAll

getAll

put

putAll

putIfAbsent

putWithTtl

putAllWithTtl

putIfAbsentWithTtl

invalidate

invalidateAll

invalidateAll

containsKey

size

estimatedSize

keys

values

entries

asMap

stats

cleanUp

async

name

l1

l2

writeStrategy

isPromoteOnL2Hit

flush

warmUp

layeredStats