Class GracefulDegradation<K,V>

java.lang.Object
cloud.opencode.base.cache.resilience.GracefulDegradation<K,V>
Type Parameters:
K - the cache key type | 缓存键类型
V - the cache value type | 缓存值类型
All Implemented Interfaces:
AutoCloseable
public final class GracefulDegradation<K,V> extends Object implements AutoCloseable
Graceful Degradation — Automatic fallback from distributed cache to local cache. 优雅降级 — 分布式缓存到本地缓存的自动故障转移。

Monitors the health of the distributed cache layer and automatically falls back to the local cache when the distributed cache becomes unavailable. Once the distributed cache recovers, the system transitions through RECOVERING back to NORMAL state.

监控分布式缓存层的健康状态，当分布式缓存不可用时自动回退到本地缓存。 一旦分布式缓存恢复，系统通过 RECOVERING 状态过渡回 NORMAL 状态。

State Machine | 状态机:

  NORMAL ──(failures >= threshold)──► DEGRADED ──(health check passes)──► RECOVERING
    ▲                                                                           │
    └──────────────(recovery window elapsed without failure)───────────────────┘
                                     RECOVERING ──(failure)──► DEGRADED

Features | 主要功能:

  • Three-state model: NORMAL, DEGRADED, RECOVERING - 三状态模型
  • Configurable failure threshold and recovery window - 可配置的失败阈值和恢复窗口
  • Automatic periodic health checks via virtual thread scheduler - 虚拟线程调度自动健康检查
  • Detailed degradation statistics - 详细的降级统计

Usage Examples | 使用示例:

GracefulDegradation<String, User> degradation = GracefulDegradation.create();

// Get with automatic fallback
Optional<User> user = degradation.get("user:123", localCache, distributedCache);

// Put with degradation awareness
degradation.put("user:123", user, Duration.ofMinutes(10), localCache, distributedCache);

// Check state and stats
GracefulDegradation.State state = degradation.state();
GracefulDegradation.Stats stats = degradation.stats();

Performance | 性能特性:

  • Lock-free state reads via volatile field - 通过 volatile 字段无锁读取状态
  • Lightweight health check via virtual thread scheduler - 虚拟线程调度器实现轻量级健康检查
  • Zero overhead in NORMAL state when distributed cache is healthy - NORMAL 状态零开销

Security | 安全性:

  • Thread-safe: Yes (volatile state, AtomicInteger/AtomicLong counters) - 线程安全: 是
  • Null-safe: No (localCache and distributedCache must not be null) - 空值安全: 否
Since:
JDK 25, opencode-base-cache V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static <K,V> GracefulDegradation<K,V> create()
      Creates a GracefulDegradation instance with default configuration. 使用默认配置创建 GracefulDegradation 实例。
      Type Parameters:
      K - the key type | 键类型
      V - the value type | 值类型
      Returns:
      a new instance with default settings | 使用默认设置的新实例

    • create

      public static <K,V> GracefulDegradation<K,V> create(GracefulDegradation.Config config)
      Creates a GracefulDegradation instance with the specified configuration. 使用指定配置创建 GracefulDegradation 实例。
      Type Parameters:
      K - the key type | 键类型
      V - the value type | 值类型
      Parameters:
      config - the degradation configuration | 降级配置
      Returns:
      a new instance with the given config | 使用给定配置的新实例

    • get

      public Optional<V> get(K key, Cache<K,V> localCache, DistributedCache<K,V> distributedCache)
      Retrieves a value, trying distributed cache first with automatic local cache fallback. 获取值，优先尝试分布式缓存并自动回退到本地缓存。

      In NORMAL/RECOVERING states, reads from distributed cache first; falls back to local on failure. In DEGRADED state, reads directly from local cache.

      在 NORMAL/RECOVERING 状态下，优先从分布式缓存读取；失败时回退到本地缓存。 在 DEGRADED 状态下，直接从本地缓存读取。

      Parameters:
      key - the cache key | 缓存键
      localCache - the local cache used as fallback | 用作回退的本地缓存
      distributedCache - the distributed cache tried first | 优先尝试的分布式缓存
      Returns:
      an Optional containing the value if found | 如果找到则包含值的 Optional

    • put

      public void put(K key, V value, Duration ttl, Cache<K,V> localCache, DistributedCache<K,V> distributedCache)
      Stores a value based on the current degradation state. 根据当前降级状态存储值。

      NORMAL: writes to both caches. DEGRADED: local only. RECOVERING: local first, then distributed.

      NORMAL: 写入两个缓存。DEGRADED: 仅本地。RECOVERING: 先本地，再分布式。

      Parameters:
      key - the cache key | 缓存键
      value - the value to store | 要存储的值
      ttl - the time-to-live | 存活时间
      localCache - the local cache | 本地缓存
      distributedCache - the distributed cache | 分布式缓存

    • state

      public GracefulDegradation.State state()
      Returns the current degradation state. 返回当前降级状态。
      Returns:
      the current state | 当前状态

    • stats

      public GracefulDegradation.Stats stats()
      Returns a snapshot of the current statistics. 返回当前统计信息的快照。
      Returns:
      the statistics snapshot | 统计信息快照

    • reset

      public void reset()
      Resets the system to NORMAL state and clears all failure counters. 将系统重置为 NORMAL 状态并清除所有失败计数器。

    • close

      public void close()
      Closes this instance and shuts down the health check executor. 关闭此实例并停止健康检查执行器。
      Specified by:
      close in interface AutoCloseable