java.lang.Object

cloud.opencode.base.cache.OpenCache

public final class OpenCache extends Object

OpenCache Facade - Unified entry point for cache operations OpenCache 门面 - 缓存操作的统一入口

Provides convenient static methods for cache creation and management.

提供便捷的静态方法用于缓存创建和管理。

Features | 主要功能:

Cache creation with fluent API - 流式 API 创建缓存
Named cache management - 命名缓存管理
Policy factory methods - 策略工厂方法
Global statistics - 全局统计

Usage Examples | 使用示例:

// Create cache with configuration - 使用配置创建缓存
Cache<String, User> cache = OpenCache.getOrCreate("users", config -> config
    .maximumSize(10000)
    .expireAfterWrite(Duration.ofMinutes(30))
    .evictionPolicy(OpenCache.lru())
    .recordStats());

// Build cache directly - 直接构建缓存
Cache<String, User> cache = OpenCache.<String, User>builder()
    .maximumSize(10000)
    .expireAfterWrite(Duration.ofMinutes(30))
    .build("myCache");

// Use policy factories - 使用策略工厂
EvictionPolicy<K, V> policy = OpenCache.wTinyLfu();
ExpiryPolicy<K, V> expiry = OpenCache.ttl(Duration.ofHours(1));

Security | 安全性:

Thread-safe: Yes - 线程安全: 是
Null-safe: Yes - 空值安全: 是

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 final class

OpenCache.CacheBuilder<K,V>

Deprecated, for removal: This API element is subject to removal in a future version.
Use CacheConfig.Builder instead for full configuration capabilities.
Method Summary

Modifier and Type

Method

Description

static <K,V> OpenCache.CacheBuilder<K,V>

builder()

Create cache configuration builder 创建缓存配置构建器

static void

cleanUpAll()

Clean up all caches 清理所有缓存

static <K,V> ExpiryPolicy<K,V>

combined(Duration ttl, Duration tti)

Create combined TTL and TTI expiry policy 创建组合 TTL 和 TTI 过期策略

static <K,V> CacheDecorators.ChainBuilder<K,V>

decorate(Cache<K,V> cache)

Start a decorator chain for the given cache 为给定的缓存开始装饰器链

static <K,V> EvictionPolicy<K,V>

fifo()

Create FIFO eviction policy 创建 FIFO 淘汰策略

static <K,V> Cache<K,V>

fifoCache(long maxSize)

Create a simple FIFO cache with given maximum size 创建具有给定最大容量的简单 FIFO 缓存

static <K,V> Cache<K,V>

fromSpec(String spec)

Create anonymous cache from specification string 从规范字符串创建匿名缓存

static <K,V> Cache<K,V>

fromSpec(String name, String spec)

Create cache from specification string 从规范字符串创建缓存

static <K,V> Optional<Cache<K,V>>

get(String name)

Get existing cache by name 按名称获取已存在的缓存

static <K,V> Cache<K,V>

getOrCreate(String name)

Get or create named cache 获取或创建命名缓存

static <K,V> Cache<K,V>

getOrCreate(String name, Consumer<CacheConfig.Builder<K,V>> configurer)

Get or create named cache with configuration 获取或创建带配置的命名缓存

static <K,V> Optional<V>

getValue(String name, K key)

Get value from named cache 从命名缓存中获取值

static <K,V> void

invalidate(String name, K key)

Invalidate a single key in named cache 使命名缓存中的单个键失效

static void

invalidateAll(String name)

Invalidate all entries in named cache 使命名缓存中的所有条目失效

static boolean

isEmpty(String name)

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

static boolean

isValidSpec(String spec)

Validate a specification string 验证规范字符串

static <K,V> EvictionPolicy<K,V>

lfu()

Create LFU eviction policy 创建 LFU 淘汰策略

static <K,V> Cache<K,V>

lfuCache(long maxSize)

Create a simple LFU cache with given maximum size 创建具有给定最大容量的简单 LFU 缓存

static <K,V> LoadingCache<K,V>

loadingCache(String name, Function<? super K, ? extends V> loader, long maxSize)

Create a loading cache with automatic value loading 创建具有自动值加载功能的加载缓存

static <K,V> LoadingCache<K,V>

loadingCache(String name, Function<? super K, ? extends V> loader, long maxSize, Duration duration)

Create a loading cache with TTL 创建具有 TTL 的加载缓存

static <K,V> EvictionPolicy<K,V>

lru()

Create LRU eviction policy 创建 LRU 淘汰策略

static <K,V> Cache<K,V>

lruCache(long maxSize)

Create a simple LRU cache with given maximum size 创建具有给定最大容量的简单 LRU 缓存

static <K,V> Cache<K,V>

lruTtlCache(long maxSize, Duration duration)

Create a cache with both LRU and TTL 创建同时具有 LRU 和 TTL 的缓存

static Set<String>

names()

Get all cache names 获取所有缓存名称

static <K,V> CacheConfig<K,V>

parseSpec(String spec)

Parse specification string to CacheConfig 解析规范字符串为 CacheConfig

static <K,V> void

put(String name, K key, V value)

Put value in named cache 在命名缓存中放入值

static void

remove(String name)

Remove cache by name 按名称移除缓存

static void

shutdown()

Shutdown cache system 关闭缓存系统

static long

size(String name)

Get size of named cache 获取命名缓存的大小

static Map<String, CacheStats>

stats()

Get global statistics 获取全局统计

static <K,V> ExpiryPolicy<K,V>

tti(Duration duration)

Create TTI expiry policy 创建 TTI 过期策略

static <K,V> Cache<K,V>

ttiCache(long maxSize, Duration duration)

Create a TTI-based cache with given size and idle expiration 创建具有给定容量和空闲过期时间的 TTI 缓存

static <K,V> ExpiryPolicy<K,V>

ttl(Duration duration)

Create TTL expiry policy 创建 TTL 过期策略

static <K,V> Cache<K,V>

ttlCache(long maxSize, Duration duration)

Create a TTL-based cache with given size and expiration 创建具有给定容量和过期时间的 TTL 缓存

static <K,V> EvictionPolicy<K,V>

wTinyLfu()

Create W-TinyLFU eviction policy with default expected size (10,000) 创建默认期望大小（10,000）的 W-TinyLFU 淘汰策略

static <K,V> EvictionPolicy<K,V>

wTinyLfu(int expectedSize)

Create W-TinyLFU eviction policy sized for the expected cache capacity 创建根据期望缓存容量调整大小的 W-TinyLFU 淘汰策略

static <K,V> Cache<K,V>

wTinyLfuCache(long maxSize)

Create a high-performance W-TinyLFU cache 创建高性能 W-TinyLFU 缓存

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- getOrCreate
  
  public static <K,V> Cache<K,V> getOrCreate(String name)
  
  Get or create named cache 获取或创建命名缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  name - cache name | 缓存名称
  
  Returns:
  
  cache instance | 缓存实例
- getOrCreate
  
  public static <K,V> Cache<K,V> getOrCreate(String name, Consumer<CacheConfig.Builder<K,V>> configurer)
  
  Get or create named cache with configuration 获取或创建带配置的命名缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  name - cache name | 缓存名称
  
  configurer - configuration consumer | 配置消费者
  
  Returns:
  
  cache instance | 缓存实例
- fromSpec
  public static <K,V> Cache<K,V> fromSpec(String name, String spec)
  
  Create cache from specification string 从规范字符串创建缓存
  Parses a comma-separated specification string to configure the cache. This is convenient for loading configuration from properties files.
  
  解析逗号分隔的规范字符串来配置缓存。便于从配置文件加载配置。
  
  Supported options | 支持的选项:
  
  maximumSize=<long> - Maximum entries | 最大条目数
  
  expireAfterWrite=<duration> - TTL (e.g., 30m, 1h, 1d) | TTL 过期
  
  expireAfterAccess=<duration> - TTI | TTI 过期
  
  evictionPolicy=<lru|lfu|fifo|wtinylfu> - Eviction policy | 淘汰策略
  
  recordStats - Enable statistics | 启用统计
  
  useVirtualThreads - Enable virtual threads | 启用虚拟线程
  
  Example | 示例:
  
  // From code | 代码中使用 Cache<String, User> cache = OpenCache.fromSpec("users", "maximumSize=10000,expireAfterWrite=30m,recordStats"); // From properties | 从配置文件 String spec = props.getProperty("cache.users.spec"); Cache<String, User> cache = OpenCache.fromSpec("users", spec);
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  name - cache name | 缓存名称
  
  spec - specification string | 规范字符串
  
  Returns:
  
  cache instance | 缓存实例
  
  Throws:
  
  OpenCacheException - if spec is invalid | 规范无效时抛出异常
  
  Since:
  
  V2.1.0
- fromSpec
  
  public static <K,V> Cache<K,V> fromSpec(String spec)
  
  Create anonymous cache from specification string 从规范字符串创建匿名缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  spec - specification string | 规范字符串
  
  Returns:
  
  cache instance | 缓存实例
  
  Throws:
  
  OpenCacheException - if spec is invalid | 规范无效时抛出异常
  
  Since:
  
  V2.1.0
- parseSpec
  
  public static <K,V> CacheConfig<K,V> parseSpec(String spec)
  
  Parse specification string to CacheConfig 解析规范字符串为 CacheConfig
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  spec - specification string | 规范字符串
  
  Returns:
  
  parsed CacheConfig | 解析后的 CacheConfig
  
  Throws:
  
  OpenCacheException - if spec is invalid | 规范无效时抛出异常
  
  Since:
  
  V2.1.0
- isValidSpec
  
  public static boolean isValidSpec(String spec)
  
  Validate a specification string 验证规范字符串
  
  Parameters:
  
  spec - specification string | 规范字符串
  
  Returns:
  
  true if valid | 有效返回 true
  
  Since:
  
  V2.1.0
- builder
  
  public static <K,V> OpenCache.CacheBuilder<K,V> builder()
  
  Create cache configuration builder 创建缓存配置构建器
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Returns:
  
  configuration builder | 配置构建器
- get
  
  public static <K,V> Optional<Cache<K,V>> get(String name)
  
  Get existing cache by name 按名称获取已存在的缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  name - cache name | 缓存名称
  
  Returns:
  
  optional containing cache | 包含缓存的 Optional
- names
  
  public static Set<String> names()
  
  Get all cache names 获取所有缓存名称
  
  Returns:
  
  set of cache names | 缓存名称集合
- remove
  
  public static void remove(String name)
  
  Remove cache by name 按名称移除缓存
  
  Parameters:
  
  name - cache name | 缓存名称
- cleanUpAll
  
  public static void cleanUpAll()
  
  Clean up all caches 清理所有缓存
- stats
  
  public static Map<String, CacheStats> stats()
  
  Get global statistics 获取全局统计
  
  Returns:
  
  map of cache name to stats | 缓存名称到统计的映射
- shutdown
  
  public static void shutdown()
  
  Shutdown cache system 关闭缓存系统
- invalidate
  
  public static <K,V> void invalidate(String name, K key)
  
  Invalidate a single key in named cache 使命名缓存中的单个键失效
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  name - cache name | 缓存名称
  
  key - key to invalidate | 要失效的键
- invalidateAll
  
  public static void invalidateAll(String name)
  
  Invalidate all entries in named cache 使命名缓存中的所有条目失效
  
  Parameters:
  
  name - cache name | 缓存名称
- isEmpty
  
  public static boolean isEmpty(String name)
  
  Check if named cache is empty 检查命名缓存是否为空
  
  Parameters:
  
  name - cache name | 缓存名称
  
  Returns:
  
  true if empty or not exists | 如果为空或不存在返回true
- size
  
  public static long size(String name)
  
  Get size of named cache 获取命名缓存的大小
  
  Parameters:
  
  name - cache name | 缓存名称
  
  Returns:
  
  cache size or 0 if not exists | 缓存大小，不存在返回0
- put
  
  public static <K,V> void put(String name, K key, V value)
  
  Put value in named cache 在命名缓存中放入值
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  name - cache name | 缓存名称
  
  key - the key | 键
  
  value - the value | 值
- getValue
  
  public static <K,V> Optional<V> getValue(String name, K key)
  
  Get value from named cache 从命名缓存中获取值
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  name - cache name | 缓存名称
  
  key - the key | 键
  
  Returns:
  
  optional containing value | 包含值的 Optional
- lruCache
  
  public static <K,V> Cache<K,V> lruCache(long maxSize)
  
  Create a simple LRU cache with given maximum size 创建具有给定最大容量的简单 LRU 缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  maxSize - maximum cache size | 最大缓存容量
  
  Returns:
  
  LRU cache | LRU 缓存
  
  Since:
  
  V2.0.2
- lfuCache
  
  public static <K,V> Cache<K,V> lfuCache(long maxSize)
  
  Create a simple LFU cache with given maximum size 创建具有给定最大容量的简单 LFU 缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  maxSize - maximum cache size | 最大缓存容量
  
  Returns:
  
  LFU cache | LFU 缓存
  
  Since:
  
  V2.0.2
- fifoCache
  
  public static <K,V> Cache<K,V> fifoCache(long maxSize)
  
  Create a simple FIFO cache with given maximum size 创建具有给定最大容量的简单 FIFO 缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  maxSize - maximum cache size | 最大缓存容量
  
  Returns:
  
  FIFO cache | FIFO 缓存
  
  Since:
  
  V2.0.2
- ttlCache
  
  public static <K,V> Cache<K,V> ttlCache(long maxSize, Duration duration)
  
  Create a TTL-based cache with given size and expiration 创建具有给定容量和过期时间的 TTL 缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  maxSize - maximum cache size | 最大缓存容量
  
  duration - time-to-live | 存活时间
  
  Returns:
  
  TTL cache | TTL 缓存
  
  Since:
  
  V2.0.2
- ttiCache
  
  public static <K,V> Cache<K,V> ttiCache(long maxSize, Duration duration)
  
  Create a TTI-based cache with given size and idle expiration 创建具有给定容量和空闲过期时间的 TTI 缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  maxSize - maximum cache size | 最大缓存容量
  
  duration - time-to-idle | 空闲时间
  
  Returns:
  
  TTI cache | TTI 缓存
  
  Since:
  
  V2.0.2
- wTinyLfuCache
  
  public static <K,V> Cache<K,V> wTinyLfuCache(long maxSize)
  
  Create a high-performance W-TinyLFU cache 创建高性能 W-TinyLFU 缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  maxSize - maximum cache size | 最大缓存容量
  
  Returns:
  
  W-TinyLFU cache | W-TinyLFU 缓存
  
  Since:
  
  V2.0.2
- lruTtlCache
  
  public static <K,V> Cache<K,V> lruTtlCache(long maxSize, Duration duration)
  
  Create a cache with both LRU and TTL 创建同时具有 LRU 和 TTL 的缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  maxSize - maximum cache size | 最大缓存容量
  
  duration - time-to-live | 存活时间
  
  Returns:
  
  LRU+TTL cache | LRU+TTL 缓存
  
  Since:
  
  V2.0.2
- loadingCache
  
  public static <K,V> LoadingCache<K,V> loadingCache(String name, Function<? super K, ? extends V> loader, long maxSize)
  
  Create a loading cache with automatic value loading 创建具有自动值加载功能的加载缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  name - cache name | 缓存名称
  
  loader - the loader function | 加载函数
  
  maxSize - maximum cache size | 最大缓存容量
  
  Returns:
  
  loading cache | 加载缓存
  
  Since:
  
  V2.0.3
- loadingCache
  
  public static <K,V> LoadingCache<K,V> loadingCache(String name, Function<? super K, ? extends V> loader, long maxSize, Duration duration)
  
  Create a loading cache with TTL 创建具有 TTL 的加载缓存
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  name - cache name | 缓存名称
  
  loader - the loader function | 加载函数
  
  maxSize - maximum cache size | 最大缓存容量
  
  duration - time-to-live | 存活时间
  
  Returns:
  
  loading cache with TTL | 具有 TTL 的加载缓存
  
  Since:
  
  V2.0.3
- decorate
  
  public static <K,V> CacheDecorators.ChainBuilder<K,V> decorate(Cache<K,V> cache)
  
  Start a decorator chain for the given cache 为给定的缓存开始装饰器链
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  cache - the cache to decorate | 要装饰的缓存
  
  Returns:
  
  decorator chain builder | 装饰器链构建器
  
  Since:
  
  V2.0.2
- lru
  
  public static <K,V> EvictionPolicy<K,V> lru()
  
  Create LRU eviction policy 创建 LRU 淘汰策略
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Returns:
  
  LRU policy | LRU 策略
- lfu
  
  public static <K,V> EvictionPolicy<K,V> lfu()
  
  Create LFU eviction policy 创建 LFU 淘汰策略
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Returns:
  
  LFU policy | LFU 策略
- fifo
  
  public static <K,V> EvictionPolicy<K,V> fifo()
  
  Create FIFO eviction policy 创建 FIFO 淘汰策略
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Returns:
  
  FIFO policy | FIFO 策略
- wTinyLfu
  
  public static <K,V> EvictionPolicy<K,V> wTinyLfu()
  
  Create W-TinyLFU eviction policy with default expected size (10,000) 创建默认期望大小（10,000）的 W-TinyLFU 淘汰策略
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Returns:
  
  W-TinyLFU policy | W-TinyLFU 策略
- wTinyLfu
  
  public static <K,V> EvictionPolicy<K,V> wTinyLfu(int expectedSize)
  
  Create W-TinyLFU eviction policy sized for the expected cache capacity 创建根据期望缓存容量调整大小的 W-TinyLFU 淘汰策略
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  expectedSize - the expected maximum number of cache entries | 期望的缓存最大条目数
  
  Returns:
  
  W-TinyLFU policy | W-TinyLFU 策略
- ttl
  
  public static <K,V> ExpiryPolicy<K,V> ttl(Duration duration)
  
  Create TTL expiry policy 创建 TTL 过期策略
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  duration - expiration duration | 过期时长
  
  Returns:
  
  TTL policy | TTL 策略
- tti
  
  public static <K,V> ExpiryPolicy<K,V> tti(Duration duration)
  
  Create TTI expiry policy 创建 TTI 过期策略
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  duration - expiration duration | 过期时长
  
  Returns:
  
  TTI policy | TTI 策略
- combined
  
  public static <K,V> ExpiryPolicy<K,V> combined(Duration ttl, Duration tti)
  
  Create combined TTL and TTI expiry policy 创建组合 TTL 和 TTI 过期策略
  
  Type Parameters:
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  ttl - TTL duration | TTL 时长
  
  tti - TTI duration | TTI 时长
  
  Returns:
  
  combined policy | 组合策略

Class OpenCache

Nested Class Summary

Method Summary

Methods inherited from class Object

Method Details

getOrCreate

getOrCreate

fromSpec

fromSpec

parseSpec

isValidSpec

builder

get

names

remove

cleanUpAll

stats

shutdown

invalidate

invalidateAll

isEmpty

size

put

getValue

lruCache

lfuCache

fifoCache

ttlCache

ttiCache

wTinyLfuCache

lruTtlCache

loadingCache

loadingCache

decorate

lru

lfu

fifo

wTinyLfu

wTinyLfu

ttl

tti

combined