Type Parameters:: K - the type of keys | 键类型; V - the type of values | 值类型

All Known Subinterfaces:: LoadingCache<K,V>

All Known Implementing Classes:: CacheTestSupport.MockCache, CacheTestSupport.RecordingCache, CompressedCache, CopyOnReadCache, LayeredCache, MultiLevelCache, NullSafeCache, ProtectedCache, ReadThroughCache, ReferenceCache, RefreshAheadCache, TaggedCache, TimeoutCache, VariableTtlCache, WriteBehindCache, WriteThroughCache

public interface Cache<K,V>

Cache Core Interface - High-performance local cache with synchronous API 缓存核心接口 - 高性能本地缓存同步 API

Provides comprehensive cache operations including get, put, invalidate and statistics.

提供完整的缓存操作，包括获取、放入、失效和统计功能。

Features | 主要功能:

Basic operations (get, put, invalidate) - 基本操作（获取、放入、失效）
Batch operations (getAll, putAll, invalidateAll) - 批量操作
Compute if absent with loader - 不存在时加载
Statistics and monitoring - 统计与监控
Async view support - 异步视图支持

Usage Examples | 使用示例:

// Get value - 获取值
User user = cache.get("user:1001");

// Get or load - 获取或加载
User user = cache.get("user:1001", key -> userService.findById(key));

// Put value - 放入值
cache.put("user:1001", user);

// Invalidate - 失效
cache.invalidate("user:1001");

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:

Field Summary

Fields

Modifier and Type

Field

Description

static final int

MAX_GLOB_LENGTH

Maximum accepted glob pattern length.
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 获取异步视图

void

cleanUp()

Perform cleanup (expired entries, etc.)

default void

clear()

Clear all entries (alias for invalidateAll, for Map API compatibility) 清空所有条目（invalidateAll 的别名，兼容 Map API）

default V

compute(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)

Compute a new value for the key 计算键的新值

default V

computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction)

Compute value if absent (alias for get with loader for Map API compatibility) 不存在时计算值（为 Map API 兼容性提供的 get with loader 别名）

default Optional<V>

computeIfMatch(K key, Predicate<V> condition, Function<V,V> remapper)

Compute new value if current value matches the condition.

default V

computeIfPresent(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)

Compute a new value if key is present 如果键存在则计算新值

boolean

containsKey(K key)

Check if key exists 检查键是否存在

default boolean

containsValue(V value)

Check if cache contains a specific value 检查缓存是否包含特定值

Set<Map.Entry<K,V>>

entries()

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

default Iterator<Map.Entry<K,V>>

entryIterator()

Get a lazy iterator over entries (memory efficient) 获取条目的惰性迭代器（内存高效）

default Stream<Map.Entry<K,V>>

entryParallelStream()

Get a parallel stream over entries 获取条目的并行流

default Stream<Map.Entry<K,V>>

entryStream()

Get a lazy stream over entries (memory efficient) 获取条目的惰性流（内存高效）

long

estimatedSize()

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

default void

forEach(BiConsumer<? super K, ? super V> action)

Iterate over all entries with a consumer (memory efficient) 使用消费者遍历所有条目（内存高效）

default void

forEachKey(Consumer<? super K> action)

Iterate over all keys with a consumer 使用消费者遍历所有键

default void

forEachValue(Consumer<? super V> action)

Iterate over all values with a consumer 使用消费者遍历所有值

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 加载

default V

getAndRemove(K key)

Get value and remove the entry atomically 原子地获取值并删除条目

default Map<K,V>

getByPattern(String pattern)

Get entries matching a key pattern 获取匹配键模式的条目

default Optional<V>

getIfPresent(K key)

Deprecated, for removal: This API element is subject to removal in a future version.
Use getOptional(Object) instead.

default Optional<V>

getOptional(K key)

Get value as Optional, distinguishing "not present" from "null value" 以 Optional 形式获取值，区分"不存在"和"值为 null"

default V

getOrDefault(K key, V defaultValue)

Get value or return default if not present 获取值，不存在则返回默认值

default V

getOrNull(K key)

Deprecated, for removal: This API element is subject to removal in a future version.
Use get(Object) instead.

void

invalidate(K key)

Invalidate a single key 使单个键失效

void

invalidateAll()

Invalidate all entries 清空所有缓存

void

invalidateAll(Iterable<? extends K> keys)

Invalidate multiple keys 批量失效

default long

invalidateByPattern(String pattern)

Invalidate entries matching a pattern (supports * and ?

default long

invalidateByValue(Predicate<V> predicate)

Invalidate entries matching a value predicate 使值满足条件的条目失效

default long

invalidateIf(Predicate<K> predicate)

Invalidate entries matching a predicate 使满足条件的条目失效

default boolean

isEmpty()

Check if cache is empty 检查缓存是否为空

default Iterator<K>

keyIterator()

Get a lazy iterator over keys (memory efficient) 获取键的惰性迭代器（内存高效）

default Stream<K>

keyParallelStream()

Get a parallel stream over keys 获取键的并行流

Set<K>

keys()

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

default Stream<K>

keyStream()

Get a lazy stream over keys (memory efficient) 获取键的惰性流（内存高效）

default V

merge(K key, V value, BiFunction<? super V, ? super V, ? extends V> mergeFunction)

Merge a value with existing value using the given function 使用给定函数合并值与现有值

default CacheMetrics

metrics()

Get detailed cache metrics with latency percentiles 获取带延迟百分位数的详细缓存指标

String

name()

Get cache name 获取缓存名称

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 批量放入

default int

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

Put all entries if their keys are absent 批量放入不存在的键的条目

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

default boolean

putIfPresent(K key, V value)

Put value only if key is present (update existing entry only) 仅在键存在时放入值（仅更新现有条目）

void

putWithTtl(K key, V value, Duration ttl)

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

default boolean

removeIfEquals(K key, V value)

Remove entry only if value matches the expected value 仅在值与期望值匹配时移除条目

default boolean

removeIfPresent(K key)

Remove entry only if key is present and return success status 仅在键存在时移除条目，并返回成功状态

default V

replace(K key, V value)

Replace value only if key is present 仅在键存在时替换值

default boolean

replace(K key, V oldValue, V newValue)

Replace value only if current value equals expected value 仅在当前值等于期望值时替换

default int

replaceAll(BiFunction<? super K, ? super V, ? extends V> function)

Replace all values using the given function 使用给定函数替换所有值

default boolean

replaceIf(K key, Predicate<V> condition, V newValue)

Replace value if current value matches the condition.

default void

resetStats()

Reset statistics counters 重置统计计数器

long

size()

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

CacheStats

stats()

Get cache statistics 获取缓存统计信息

default int

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

Update only existing entries (does not insert new ones) 仅更新现有条目（不插入新条目）

default long

updateTtl(Iterable<? extends K> keys, Duration ttl)

Update TTL for specific keys 更新指定键的 TTL

default long

updateTtl(Predicate<K> predicate, Duration ttl)

Update TTL for existing entries matching predicate 更新匹配条件的现有条目的 TTL

default long

updateTtlAll(Duration ttl)

Update TTL for all entries 更新所有条目的 TTL

default Stream<V>

valueParallelStream()

Get a parallel stream over values 获取值的并行流

Collection<V>

values()

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

default Stream<V>

valueStream()

Get a lazy stream over values (memory efficient) 获取值的惰性流（内存高效）

Field Details
- MAX_GLOB_LENGTH
  static final int MAX_GLOB_LENGTH
  
  Maximum accepted glob pattern length. V1.0.4 sec round-4 P1: a user-controlled glob with many * stars (which become .*) plus literal anchors produces a regex like .*a.*b.*c.*d...x that on long keys triggers catastrophic backtracking — classic ReDoS. Capping at 256 chars puts the practical bound far below any realistic cache pattern length while leaving regex worst-case backtracking bounded. glob 模式最大长度。V1.0.4 sec round-4 P1：用户控制的 glob 含大量 *（转为 .*）加字面 anchor，会产生 .*a.*b.*c.*d...x 形态的正则；对长 key 触发灾难性回溯，是经典 ReDoS。封顶 256 字符既远超实际缓存模式长度，又把正则最坏回溯限制在可控范围。
  Note: Interface fields are implicitly public static final; private is not allowed on interface fields, so the constant is exposed by language design. 接口字段隐式 public static final；接口字段不允许 private，故常量按语言规则导出。
  
  See Also:
  
  Constant Field Values
Method Details
- get
  
  V get(K key)
  
  Get value by key, returns null if not present 根据键获取值，不存在返回 null
  
  Parameters:
  
  key - the key | 键
  
  Returns:
  
  the value or null | 值或 null
- get
  
  V get(K key, Function<? super K, ? extends V> loader)
  
  Get value by key, load using loader if not present 根据键获取值，不存在时通过 loader 加载
  
  Parameters:
  
  key - the key | 键
  
  loader - the loader function | 加载函数
  
  Returns:
  
  the value | 值
- getAll
  
  Map<K,V> getAll(Iterable<? extends K> keys)
  
  Get all values for given keys, returns only existing entries 批量获取，仅返回存在的条目
  
  Parameters:
  
  keys - the keys | 键集合
  
  Returns:
  
  map of existing entries | 存在的条目 Map
- getAll
  
  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 加载
  
  Parameters:
  
  keys - the keys | 键集合
  
  loader - the batch loader function | 批量加载函数
  
  Returns:
  
  map of all entries | 所有条目 Map
- put
  
  void put(K key, V value)
  
  Put a key-value pair into cache 放入键值对
  
  Parameters:
  
  key - the key | 键
  
  value - the value | 值
- putAll
  
  void putAll(Map<? extends K, ? extends V> map)
  
  Put all key-value pairs into cache 批量放入
  
  Parameters:
  
  map - the key-value pairs | 键值对 Map
- putIfAbsent
  
  boolean putIfAbsent(K key, V value)
  
  Put if the key is absent, returns true if successful 不存在时放入，成功返回 true
  
  Parameters:
  
  key - the key | 键
  
  value - the value | 值
  
  Returns:
  
  true if put successfully | 成功放入返回 true
- putWithTtl
  
  void putWithTtl(K key, V value, Duration ttl)
  
  Put a key-value pair with custom TTL (overrides default expiration) 放入键值对并指定自定义 TTL（覆盖默认过期时间）
  
  Parameters:
  
  key - the key | 键
  
  value - the value | 值
  
  ttl - the time-to-live for this entry | 此条目的存活时间
- putAllWithTtl
  
  void putAllWithTtl(Map<? extends K, ? extends V> map, Duration ttl)
  
  Put all entries with custom TTL 批量放入并指定自定义 TTL
  
  Parameters:
  
  map - the key-value pairs | 键值对 Map
  
  ttl - the time-to-live for all entries | 所有条目的存活时间
- putIfAbsentWithTtl
  
  boolean putIfAbsentWithTtl(K key, V value, Duration ttl)
  
  Put if absent with custom TTL 不存在时放入并指定自定义 TTL
  
  Parameters:
  
  key - the key | 键
  
  value - the value | 值
  
  ttl - the time-to-live | 存活时间
  
  Returns:
  
  true if put successfully | 成功放入返回 true
- getOrDefault
  
  default V getOrDefault(K key, V defaultValue)
  
  Get value or return default if not present 获取值，不存在则返回默认值
  
  Parameters:
  
  key - the key | 键
  
  defaultValue - the default value | 默认值
  
  Returns:
  
  the value or default | 值或默认值
- computeIfPresent
  
  default V computeIfPresent(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)
  
  Compute a new value if key is present 如果键存在则计算新值
  If the key is present and the remapping function returns non-null, the value is replaced. If the function returns null, the entry is removed.
  
  如果键存在且映射函数返回非 null，则替换值。如果函数返回 null，则删除条目。
  
  Parameters:
  
  key - the key | 键
  
  remappingFunction - the function to compute new value | 计算新值的函数
  
  Returns:
  
  the new value or null if removed/absent | 新值，如果被删除或不存在则返回 null
- compute
  
  default V compute(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)
  
  Compute a new value for the key 计算键的新值
  Atomically computes a new value. If the key is absent and the function returns non-null, a new entry is created. If the key is present and the function returns null, the entry is removed.
  
  原子地计算新值。如果键不存在且函数返回非 null，则创建新条目。如果键存在且函数返回 null，则删除条目。
  
  Parameters:
  
  key - the key | 键
  
  remappingFunction - the function to compute value | 计算值的函数
  
  Returns:
  
  the new value or null if removed | 新值，如果被删除则返回 null
- getAndRemove
  
  default V getAndRemove(K key)
  
  Get value and remove the entry atomically 原子地获取值并删除条目
  
  Parameters:
  
  key - the key | 键
  
  Returns:
  
  the value or null if not present | 值，不存在则返回 null
- replace
  
  default V replace(K key, V value)
  
  Replace value only if key is present 仅在键存在时替换值
  
  Parameters:
  
  key - the key | 键
  
  value - the new value | 新值
  
  Returns:
  
  the old value or null if not present | 旧值，不存在则返回 null
- replace
  
  default boolean replace(K key, V oldValue, V newValue)
  
  Replace value only if current value equals expected value 仅在当前值等于期望值时替换
  
  Parameters:
  
  key - the key | 键
  
  oldValue - the expected current value | 期望的当前值
  
  newValue - the new value | 新值
  
  Returns:
  
  true if replaced | 替换成功返回 true
- getOptional
  
  default Optional<V> getOptional(K key)
  
  Get value as Optional, distinguishing "not present" from "null value" 以 Optional 形式获取值，区分"不存在"和"值为 null"
  Unlike get(Object), this method can distinguish between a key that is not present and a key that is present with a null value.
  
  与 get(Object) 不同，此方法可以区分键不存在和键存在但值为 null 的情况。
  
  Parameters:
  
  key - the key | 键
  
  Returns:
  
  Optional containing the value, or empty if key not present | 包含值的 Optional，键不存在则返回空
  
  Since:
  
  V1.0.0
- getIfPresent
  
  @Deprecated(since="1.0.3", forRemoval=true) default Optional<V> getIfPresent(K key)
  
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use getOptional(Object) instead.
  
  Get value only if present, without triggering loader 仅在存在时获取值，不触发加载器
  This is useful when you want to check the cache without side effects.
  
  当您想检查缓存而不产生副作用时，此方法很有用。
  
  Parameters:
  
  key - the key | 键
  
  Returns:
  
  Optional containing the value, or empty if not present | 包含值的 Optional，不存在则返回空
  
  Since:
  
  V1.0.0
- merge
  
  default V merge(K key, V value, BiFunction<? super V, ? super V, ? extends V> mergeFunction)
  
  Merge a value with existing value using the given function 使用给定函数合并值与现有值
  If the key is absent, the provided value is used. If the key is present, the merge function is called with the old and new values.
  
  如果键不存在，使用提供的值。如果键存在，使用旧值和新值调用合并函数。
  
  Parameters:
  
  key - the key | 键
  
  value - the value to merge | 要合并的值
  
  mergeFunction - the function to merge values | 合并函数
  
  Returns:
  
  the new value | 新值
  
  Since:
  
  V1.0.0
  
  API Note:
  
  This operation is NOT atomic — it consists of a get followed by put/invalidate, which is subject to TOCTOU race conditions under concurrent access. | 此操作非原子性 — 由 get 和 put/invalidate 组成，在并发访问下存在 TOCTOU 竞态。
- computeIfAbsent
  
  default V computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction)
  
  Compute value if absent (alias for get with loader for Map API compatibility) 不存在时计算值（为 Map API 兼容性提供的 get with loader 别名）
  
  Parameters:
  
  key - the key | 键
  
  mappingFunction - the function to compute value | 计算值的函数
  
  Returns:
  
  the value | 值
  
  Since:
  
  V1.0.0
- putIfPresent
  
  default boolean putIfPresent(K key, V value)
  
  Put value only if key is present (update existing entry only) 仅在键存在时放入值（仅更新现有条目）
  Unlike put(Object, Object), this does not create a new entry if the key is not present.
  
  与 put(Object, Object) 不同，如果键不存在则不创建新条目。
  
  Parameters:
  
  key - the key | 键
  
  value - the value | 值
  
  Returns:
  
  true if updated, false if key was not present | 更新成功返回 true，键不存在返回 false
  
  Since:
  
  V1.0.0
  
  API Note:
  
  This operation is NOT atomic — it consists of a containsKey check followed by put, which is subject to TOCTOU race conditions under concurrent access. | 此操作非原子性 — 由 containsKey 检查和 put 组成，在并发访问下存在 TOCTOU 竞态。
- containsValue
  
  default boolean containsValue(V value)
  
  Check if cache contains a specific value 检查缓存是否包含特定值
  Warning: This operation is O(n) as it scans all values.
  
  警告：此操作为 O(n)，因为它扫描所有值。
  
  Parameters:
  
  value - the value to check | 要检查的值
  
  Returns:
  
  true if value exists | 值存在返回 true
  
  Since:
  
  V1.0.0
  
  API Note:
  
  This operation requires O(n) scan of all cached values and may be slow for large caches. | 此操作需要 O(n) 扫描所有缓存值，大缓存场景下可能较慢。
- getOrNull
  
  @Deprecated(since="1.0.3", forRemoval=true) default V getOrNull(K key)
  
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use get(Object) instead.
  
  Get value or null if not present (explicit null return) 获取值，不存在时显式返回 null
  This is semantically equivalent to get(Object) but makes the null return value explicit in the method name.
  
  这在语义上等同于 get(Object)，但在方法名中明确表示返回 null。
  
  Parameters:
  
  key - the key | 键
  
  Returns:
  
  the value or null | 值或 null
  
  Since:
  
  V1.0.0
- replaceAll
  
  default int replaceAll(BiFunction<? super K, ? super V, ? extends V> function)
  
  Replace all values using the given function 使用给定函数替换所有值
  
  Parameters:
  
  function - the function to transform values | 转换值的函数
  
  Returns:
  
  count of replaced entries | 替换的条目数
  
  Since:
  
  V1.0.0
- forEachValue
  
  default void forEachValue(Consumer<? super V> action)
  
  Iterate over all values with a consumer 使用消费者遍历所有值
  
  Parameters:
  
  action - the action to perform on each value | 对每个值执行的操作
  
  Since:
  
  V1.0.0
- forEachKey
  
  default void forEachKey(Consumer<? super K> action)
  
  Iterate over all keys with a consumer 使用消费者遍历所有键
  
  Parameters:
  
  action - the action to perform on each key | 对每个键执行的操作
  
  Since:
  
  V1.0.0
- removeIfPresent
  
  default boolean removeIfPresent(K key)
  
  Remove entry only if key is present and return success status 仅在键存在时移除条目，并返回成功状态
  
  Parameters:
  
  key - the key | 键
  
  Returns:
  
  true if removed, false if key was not present | 移除成功返回 true，键不存在返回 false
  
  Since:
  
  V1.0.0
  
  API Note:
  
  This operation is NOT atomic — it consists of a containsKey check followed by invalidate, which is subject to TOCTOU race conditions under concurrent access. | 此操作非原子性 — 由 containsKey 检查和 invalidate 组成，在并发访问下存在 TOCTOU 竞态。
- removeIfEquals
  
  default boolean removeIfEquals(K key, V value)
  
  Remove entry only if value matches the expected value 仅在值与期望值匹配时移除条目
  
  Parameters:
  
  key - the key | 键
  
  value - the expected value | 期望的值
  
  Returns:
  
  true if removed | 移除成功返回 true
  
  Since:
  
  V1.0.0
  
  API Note:
  
  This operation is NOT atomic — it consists of a containsKey check followed by invalidate, which is subject to TOCTOU race conditions under concurrent access. | 此操作非原子性 — 由 containsKey 检查和 invalidate 组成，在并发访问下存在 TOCTOU 竞态。
- getByPattern
  default Map<K,V> getByPattern(String pattern)
  
  Get entries matching a key pattern 获取匹配键模式的条目
  Pattern syntax:
  
  * - matches any sequence of characters
  
  ? - matches any single character
  
  Parameters:
  
  pattern - the pattern to match | 匹配模式
  
  Returns:
  
  map of matching entries | 匹配的条目 Map
  
  Since:
  
  V1.0.0
- putAllIfAbsent
  
  default int putAllIfAbsent(Map<? extends K, ? extends V> map)
  
  Put all entries if their keys are absent 批量放入不存在的键的条目
  
  Parameters:
  
  map - the entries to put | 要放入的条目
  
  Returns:
  
  count of entries actually put | 实际放入的条目数
  
  Since:
  
  V1.0.0
- updateAll
  
  default int updateAll(Map<? extends K, ? extends V> map)
  
  Update only existing entries (does not insert new ones) 仅更新现有条目（不插入新条目）
  
  Parameters:
  
  map - the entries to update | 要更新的条目
  
  Returns:
  
  count of entries actually updated | 实际更新的条目数
  
  Since:
  
  V1.0.0
- invalidate
  
  void invalidate(K key)
  
  Invalidate a single key 使单个键失效
  
  Parameters:
  
  key - the key to invalidate | 要失效的键
- invalidateAll
  
  void invalidateAll(Iterable<? extends K> keys)
  
  Invalidate multiple keys 批量失效
  
  Parameters:
  
  keys - the keys to invalidate | 要失效的键集合
- invalidateAll
  
  void invalidateAll()
  
  Invalidate all entries 清空所有缓存
- clear
  
  default void clear()
  
  Clear all entries (alias for invalidateAll, for Map API compatibility) 清空所有条目（invalidateAll 的别名，兼容 Map API）
  
  Since:
  
  V1.0.0
- invalidateByPattern
  default long invalidateByPattern(String pattern)
  
  Invalidate entries matching a pattern (supports * and ? wildcards) 使匹配模式的条目失效（支持 * 和 ? 通配符）
  Pattern syntax:
  
  * - matches any sequence of characters
  
  ? - matches any single character
  
  Examples | 示例:
  
  cache.invalidateByPattern("user:*"); // Invalidate all user entries cache.invalidateByPattern("*.temp"); // Invalidate entries ending with .temp cache.invalidateByPattern("session:???"); // Invalidate 3-char session IDs
  
  Parameters:
  
  pattern - the pattern to match (supports * and ? wildcards) | 匹配模式
  
  Returns:
  
  count of invalidated entries | 失效的条目数
  
  Since:
  
  V1.0.0
- invalidateIf
  default long invalidateIf(Predicate<K> predicate)
  
  Invalidate entries matching a predicate 使满足条件的条目失效
  Examples | 示例:
  
  // Invalidate all entries with keys starting with "temp:" cache.invalidateIf(key -> key.toString().startsWith("temp:")); // Invalidate entries with numeric keys greater than 1000 cache.invalidateIf(key -> ((Integer)key) > 1000);
  
  Parameters:
  
  predicate - the predicate to test keys | 键测试条件
  
  Returns:
  
  count of invalidated entries | 失效的条目数
  
  Since:
  
  V1.0.0
- invalidateByValue
  
  default long invalidateByValue(Predicate<V> predicate)
  
  Invalidate entries matching a value predicate 使值满足条件的条目失效
  
  Parameters:
  
  predicate - the predicate to test values | 值测试条件
  
  Returns:
  
  count of invalidated entries | 失效的条目数
  
  Since:
  
  V1.0.0
- containsKey
  
  boolean containsKey(K key)
  
  Check if key exists 检查键是否存在
  
  Parameters:
  
  key - the key | 键
  
  Returns:
  
  true if exists | 存在返回 true
- size
  
  long size()
  
  Get exact entry count (may be slow) 获取精确条目数（可能较慢）
  
  Returns:
  
  entry count | 条目数
- estimatedSize
  
  long estimatedSize()
  
  Get estimated entry count (fast) 获取估算条目数（快速）
  
  Returns:
  
  estimated count | 估算数量
- isEmpty
  
  default boolean isEmpty()
  
  Check if cache is empty 检查缓存是否为空
  
  Returns:
  
  true if empty | 为空返回 true
  
  Since:
  
  V1.0.0
- keys
  
  Set<K> keys()
  
  Get snapshot of all keys 获取所有键的快照
  
  Returns:
  
  set of keys | 键集合
- values
  
  Collection<V> values()
  
  Get snapshot of all values 获取所有值的快照
  
  Returns:
  
  collection of values | 值集合
- entries
  
  Set<Map.Entry<K,V>> entries()
  
  Get snapshot of all entries 获取所有条目的快照
  
  Returns:
  
  set of entries | 条目集合
- asMap
  
  ConcurrentMap<K,V> asMap()
  
  Get a concurrent map view of this cache 获取 ConcurrentMap 视图
  
  Returns:
  
  concurrent map view | ConcurrentMap 视图
- keyIterator
  
  default Iterator<K> keyIterator()
  
  Get a lazy iterator over keys (memory efficient) 获取键的惰性迭代器（内存高效）
  Unlike keys(), this does not create a snapshot copy.
  
  与 keys() 不同，这不会创建快照副本。
  
  Returns:
  
  lazy iterator over keys | 键的惰性迭代器
  
  Since:
  
  V1.0.0
- entryIterator
  
  default Iterator<Map.Entry<K,V>> entryIterator()
  
  Get a lazy iterator over entries (memory efficient) 获取条目的惰性迭代器（内存高效）
  
  Returns:
  
  lazy iterator over entries | 条目的惰性迭代器
  
  Since:
  
  V1.0.0
- forEach
  
  default void forEach(BiConsumer<? super K, ? super V> action)
  
  Iterate over all entries with a consumer (memory efficient) 使用消费者遍历所有条目（内存高效）
  
  Parameters:
  
  action - the action to perform | 要执行的操作
  
  Since:
  
  V1.0.0
- keyStream
  
  default Stream<K> keyStream()
  
  Get a lazy stream over keys (memory efficient) 获取键的惰性流（内存高效）
  Creates a stream directly from the underlying map without creating intermediate collections. Ideal for large caches where collecting all keys would be expensive.
  
  直接从底层映射创建流，不创建中间集合。适用于收集所有键成本较高的大型缓存。
  
  Returns:
  
  lazy stream over keys | 键的惰性流
  
  Since:
  
  V1.0.0
- valueStream
  
  default Stream<V> valueStream()
  
  Get a lazy stream over values (memory efficient) 获取值的惰性流（内存高效）
  
  Returns:
  
  lazy stream over values | 值的惰性流
  
  Since:
  
  V1.0.0
- entryStream
  
  default Stream<Map.Entry<K,V>> entryStream()
  
  Get a lazy stream over entries (memory efficient) 获取条目的惰性流（内存高效）
  
  Returns:
  
  lazy stream over entries | 条目的惰性流
  
  Since:
  
  V1.0.0
- keyParallelStream
  
  default Stream<K> keyParallelStream()
  
  Get a parallel stream over keys 获取键的并行流
  Use for CPU-intensive operations on large caches.
  
  用于大型缓存上的 CPU 密集型操作。
  
  Returns:
  
  parallel stream over keys | 键的并行流
  
  Since:
  
  V1.0.0
- valueParallelStream
  
  default Stream<V> valueParallelStream()
  
  Get a parallel stream over values 获取值的并行流
  
  Returns:
  
  parallel stream over values | 值的并行流
  
  Since:
  
  V1.0.0
- entryParallelStream
  
  default Stream<Map.Entry<K,V>> entryParallelStream()
  
  Get a parallel stream over entries 获取条目的并行流
  
  Returns:
  
  parallel stream over entries | 条目的并行流
  
  Since:
  
  V1.0.0
- updateTtl
  
  default long updateTtl(Predicate<K> predicate, Duration ttl)
  
  Update TTL for existing entries matching predicate 更新匹配条件的现有条目的 TTL
  Note: This re-puts entries with new TTL. Original values are preserved.
  
  注意：这会用新的 TTL 重新放入条目。原始值保持不变。
  
  Parameters:
  
  predicate - condition for keys to update | 要更新的键条件
  
  ttl - new TTL | 新的 TTL
  
  Returns:
  
  count of updated entries | 更新的条目数
  
  Since:
  
  V1.0.0
- updateTtlAll
  
  default long updateTtlAll(Duration ttl)
  
  Update TTL for all entries 更新所有条目的 TTL
  
  Parameters:
  
  ttl - new TTL | 新的 TTL
  
  Returns:
  
  count of updated entries | 更新的条目数
  
  Since:
  
  V1.0.0
- updateTtl
  
  default long updateTtl(Iterable<? extends K> keys, Duration ttl)
  
  Update TTL for specific keys 更新指定键的 TTL
  
  Parameters:
  
  keys - keys to update | 要更新的键
  
  ttl - new TTL | 新的 TTL
  
  Returns:
  
  count of updated entries | 更新的条目数
  
  Since:
  
  V1.0.0
- replaceIf
  
  default boolean replaceIf(K key, Predicate<V> condition, V newValue)
  
  Replace value if current value matches the condition. 如果当前值满足条件则替换。
  Atomically checks the condition and replaces the value. Returns true if the replacement was made.
  
  原子地检查条件并替换值。如果替换成功则返回 true。
  
  Note | 注意: The default implementation is NOT atomic — there is a gap between get and put. Concrete implementations (e.g. DefaultCache) may override this to provide true atomicity via ConcurrentHashMap.compute.
  
  默认实现非原子性 — get 和 put 之间存在间隙。具体实现（如 DefaultCache）可覆盖此方法，通过 ConcurrentHashMap.compute 提供真正的原子保证。
  
  Parameters:
  
  key - the key | 键
  
  condition - the condition to check against current value | 对当前值的检查条件
  
  newValue - the new value | 新值
  
  Returns:
  
  true if replaced | 是否替换成功
  
  Since:
  
  V1.0.3
- computeIfMatch
  
  default Optional<V> computeIfMatch(K key, Predicate<V> condition, Function<V,V> remapper)
  
  Compute new value if current value matches the condition. 如果当前值满足条件则计算新值。
  Checks the condition and applies the remapping function. Returns the new value if computed, empty otherwise.
  
  检查条件并应用映射函数。如果计算成功则返回新值，否则返回空。
  
  Note | 注意: The default implementation is NOT atomic — there is a gap between get and put. Concrete implementations (e.g. DefaultCache) may override this to provide true atomicity via ConcurrentHashMap.compute.
  
  默认实现非原子性 — get 和 put 之间存在间隙。具体实现（如 DefaultCache）可覆盖此方法，通过 ConcurrentHashMap.compute 提供真正的原子保证。
  
  Parameters:
  
  key - the key | 键
  
  condition - the condition to check | 检查条件
  
  remapper - the remapping function | 映射函数
  
  Returns:
  
  the new value if computed | 计算出的新值（未计算则为空）
  
  Since:
  
  V1.0.3
- stats
  
  CacheStats stats()
  
  Get cache statistics 获取缓存统计信息
  
  Returns:
  
  cache statistics | 缓存统计
- metrics
  
  default CacheMetrics metrics()
  
  Get detailed cache metrics with latency percentiles 获取带延迟百分位数的详细缓存指标
  
  Returns:
  
  cache metrics or null if not enabled | 缓存指标，未启用则返回 null
- resetStats
  
  default void resetStats()
  
  Reset statistics counters 重置统计计数器
  Clears all hit, miss, load, and eviction counters to zero. Also resets metrics if enabled.
  
  将所有命中、未命中、加载和淘汰计数器清零。如果启用，也重置指标。
  
  Since:
  
  V1.0.0
- cleanUp
  
  void cleanUp()
  
  Perform cleanup (expired entries, etc.) 执行清理（过期条目等）
- async
  
  AsyncCache<K,V> async()
  
  Get async view of this cache 获取异步视图
  
  Returns:
  
  async cache view | 异步缓存视图
- name
  
  String name()
  
  Get cache name 获取缓存名称
  
  Returns:
  
  cache name | 缓存名称

Interface Cache<K,V>

Field Summary

Method Summary

Field Details

MAX_GLOB_LENGTH

Method Details

get

get

getAll

getAll

put

putAll

putIfAbsent

putWithTtl

putAllWithTtl

putIfAbsentWithTtl

getOrDefault

computeIfPresent

compute

getAndRemove

replace

replace

getOptional

getIfPresent

merge

computeIfAbsent

putIfPresent

containsValue

getOrNull

replaceAll

forEachValue

forEachKey

removeIfPresent

removeIfEquals

getByPattern

putAllIfAbsent

updateAll

invalidate

invalidateAll

invalidateAll

clear

invalidateByPattern

invalidateIf

invalidateByValue

containsKey

size

estimatedSize

isEmpty

keys

values

entries

asMap

keyIterator

entryIterator

forEach

keyStream

valueStream

entryStream

keyParallelStream

valueParallelStream

entryParallelStream

updateTtl

updateTtlAll

updateTtl

replaceIf

computeIfMatch

stats

metrics

resetStats

cleanUp

async

name