Class CopyOnReadCache<K,V>

java.lang.Object

cloud.opencode.base.cache.CopyOnReadCache<K,V>

Type Parameters:

K - key type | 键类型

V - value type | 值类型

Features | 主要功能:

• Deep copy on read operations - 读操作时深拷贝
• Optional copy on write - 可选写时复制
• Custom copier support - 自定义复制器支持
• Serialization-based default copy - 基于序列化的默认复制

Security | 安全性:

• Thread-safe: Yes (delegates to thread-safe cache) - 线程安全: 是（委托给线程安全的缓存）
• Null-safe: Yes - 空值安全: 是

All Implemented Interfaces:

Cache<K,V>

public final class CopyOnReadCache<K,V>
extends Object
implements Cache<K,V>

Copy-on-Read Cache - Returns deep copies of cached values for thread safety 读时复制缓存 - 返回缓存值的深拷贝以保证线程安全

Wraps an existing cache to return deep copies of values on read operations. This prevents external modifications from affecting cached data.

包装现有缓存，在读取操作时返回值的深拷贝。这防止外部修改影响缓存数据。

Use Cases | 使用场景:

• Mutable cached objects that might be modified by callers | 可能被调用者修改的可变缓存对象
• Thread-safe access to cached collections | 线程安全访问缓存集合
• Isolation between cache consumers | 缓存消费者之间的隔离

Usage Examples | 使用示例:

// With default deep copy (Java serialization)
Cache<String, User> cache = OpenCache.getOrCreate("users");
CopyOnReadCache<String, User> copyCache = CopyOnReadCache.wrap(cache).build();

User user = copyCache.get("user:1");
user.setName("Modified");  // Does not affect cached value

// With custom copier
CopyOnReadCache<String, Config> configCache = CopyOnReadCache.wrap(cache)
    .copier(config -> config.toBuilder().build())  // Use builder pattern
    .build();

// With Jackson for JSON-based copy
ObjectMapper mapper = new ObjectMapper();
CopyOnReadCache<String, Data> dataCache = CopyOnReadCache.wrap(cache)
    .copier(data -> mapper.readValue(mapper.writeValueAsBytes(data), Data.class))
    .build();

Since:

JDK 25, opencode-base-cache V2.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

• OpenCode.cloud

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	CopyOnReadCache.Builder<K,V>	Builder for CopyOnReadCache

Field Summary

Fields inherited from interface Cache

MAX_GLOB_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.)
V	compute(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)	Compute a new value for the key 计算键的新值
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 检查键是否存在
Set<Map.Entry<K,V>>	entries()	Get snapshot of all entries 获取所有条目的快照
long	estimatedSize()	Get estimated entry count (fast) 获取估算条目数（快速）
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 加载
V	getAndRemove(K key)	Get value and remove the entry atomically 原子地获取值并删除条目
V	getOrDefault(K key, V defaultValue)	Get value or return default if not present 获取值，不存在则返回默认值
void	invalidate(K key)	Invalidate a single key 使单个键失效
void	invalidateAll()	Invalidate all entries 清空所有缓存
void	invalidateAll(Iterable<? extends K> keys)	Invalidate multiple keys 批量失效
Set<K>	keys()	Get snapshot of all keys 获取所有键的快照
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 批量放入
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（覆盖默认过期时间）
V	replace(K key, V value)	Replace value only if key is present 仅在键存在时替换值
boolean	replace(K key, V oldValue, V newValue)	Replace value only if current value equals expected value 仅在当前值等于期望值时替换
long	size()	Get exact entry count (may be slow) 获取精确条目数（可能较慢）
CacheStats	stats()	Get cache statistics 获取缓存统计信息
Collection<V>	values()	Get snapshot of all values 获取所有值的快照
static <K,V> CopyOnReadCache.Builder<K,V>	wrap(Cache<K,V> cache)	Wrap a cache with copy-on-read behavior 使用读时复制行为包装缓存

Methods inherited from class Object

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

Methods inherited from interface Cache

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

Method Details

wrap

public static <K,V> CopyOnReadCache.Builder<K,V> wrap(Cache<K,V> cache)

Wrap a cache with copy-on-read behavior 使用读时复制行为包装缓存

Type Parameters:

K - key type | 键类型

V - value type | 值类型

Parameters:

cache - cache to wrap | 要包装的缓存

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

getOrDefault

public V getOrDefault(K key,
 V defaultValue)

Description copied from interface: Cache

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

Specified by:

getOrDefault in interface Cache<K,V>

Parameters:

key - the key | 键

defaultValue - the default value | 默认值

Returns:

the value or default | 值或默认值

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

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 | 条目集合

getAndRemove

public V getAndRemove(K key)

Description copied from interface: Cache

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

Specified by:

getAndRemove in interface Cache<K,V>

Parameters:

key - the key | 键

Returns:

the value or null if not present | 值，不存在则返回 null

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

computeIfPresent

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

Description copied from interface: Cache

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，则删除条目。

Specified by:

computeIfPresent in interface Cache<K,V>

Parameters:

key - the key | 键

remappingFunction - the function to compute new value | 计算新值的函数

Returns:

the new value or null if removed/absent | 新值，如果被删除或不存在则返回 null

compute

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

Description copied from interface: Cache

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，则删除条目。

Specified by:

compute in interface Cache<K,V>

Parameters:

key - the key | 键

remappingFunction - the function to compute value | 计算值的函数

Returns:

the new value or null if removed | 新值，如果被删除则返回 null

replace

public V replace(K key,
 V value)

Description copied from interface: Cache

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

Specified by:

replace in interface Cache<K,V>

Parameters:

key - the key | 键

value - the new value | 新值

Returns:

the old value or null if not present | 旧值，不存在则返回 null

replace

public boolean replace(K key,
 V oldValue,
 V newValue)

Description copied from interface: Cache

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

Specified by:

replace in interface Cache<K,V>

Parameters:

key - the key | 键

oldValue - the expected current value | 期望的当前值

newValue - the new value | 新值

Returns:

true if replaced | 替换成功返回 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 | 键集合

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 | 缓存统计

metrics

public CacheMetrics metrics()

Description copied from interface: Cache

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

Specified by:

metrics in interface Cache<K,V>

Returns:

cache metrics or null if not enabled | 缓存指标，未启用则返回 null

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 | 缓存名称