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

Functional Interface:: This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface public interface RefreshAheadPolicy<K,V>

Refresh Ahead Policy - Proactive cache refresh strategy 提前刷新策略 - 主动缓存刷新策略

Allows proactive refresh of cache entries before they expire, ensuring cache hits even during refresh. This prevents cache stampede and improves latency by refreshing entries in the background.

允许在缓存条目过期前主动刷新，确保在刷新期间仍能命中缓存。这可以防止缓存击穿并通过后台刷新提高延迟性能。

Features | 主要功能:

Proactive refresh before expiration - 过期前主动刷新
Background async refresh - 后台异步刷新
Stale-while-revalidate pattern - 验证时提供过期数据模式
Configurable refresh threshold - 可配置的刷新阈值

Usage Examples | 使用示例:

// Refresh when 80% of TTL has elapsed - 当 TTL 过了 80% 时刷新
RefreshAheadPolicy<String, User> policy = RefreshAheadPolicy.percentageOfTtl(0.8);

// Refresh 30 seconds before expiration - 过期前 30 秒刷新
RefreshAheadPolicy<String, User> policy = RefreshAheadPolicy.beforeExpiration(Duration.ofSeconds(30));

// Custom policy - 自定义策略
RefreshAheadPolicy<String, User> policy = RefreshAheadPolicy.custom(
    (key, age, ttl) -> age > ttl.toMillis() * 0.7
);

Security | 安全性:

Thread-safe: Yes - 线程安全: 是
Non-blocking: Yes (async refresh) - 非阻塞: 是（异步刷新）

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

Interface

Description

static interface

RefreshAheadPolicy.RefreshPredicate<K>

Predicate interface for custom refresh logic 用于自定义刷新逻辑的断言接口
Method Summary

Modifier and Type

Method

Description

static <K,V> RefreshAheadPolicy<K,V>

adaptive(double minPercentage, double maxPercentage)

Create a refresh policy with adaptive threshold based on load 创建基于负载的自适应阈值刷新策略

default RefreshAheadPolicy<K,V>

and(RefreshAheadPolicy<K,V> other)

Combine with another policy using AND logic 使用 AND 逻辑与另一个策略组合

static <K,V> RefreshAheadPolicy<K,V>

beforeExpiration(Duration beforeExpiration)

Create a policy that refreshes a fixed duration before expiration 创建在过期前固定时间刷新的策略

static <K,V> RefreshAheadPolicy<K,V>

custom(RefreshAheadPolicy.RefreshPredicate<K> predicate)

Create a custom refresh policy 创建自定义刷新策略

static <K,V> RefreshAheadPolicy<K,V>

disabled()

Create a disabled policy (no refresh ahead) 创建禁用的策略（不提前刷新）

default void

onRefreshFailure(K key, V oldValue, Throwable error)

Called when refresh fails 刷新失败时调用

default void

onRefreshSuccess(K key, V oldValue, V newValue)

Called after successful refresh 刷新成功后调用

default RefreshAheadPolicy<K,V>

or(RefreshAheadPolicy<K,V> other)

Combine with another policy using OR logic 使用 OR 逻辑与另一个策略组合

static <K,V> RefreshAheadPolicy<K,V>

percentageOfTtl(double percentage)

Create a policy that refreshes when a percentage of TTL has elapsed 创建当 TTL 过了指定百分比时刷新的策略

default Executor

refreshExecutor()

Get the refresh executor (default: common pool) 获取刷新执行器（默认: 公共池）

boolean

shouldRefresh(K key, long ageMillis, long ttlMillis)

Determine if an entry should be refreshed 确定条目是否应该刷新

static <K,V> RefreshAheadPolicy<K,V>

withJitter(double basePercentage, double jitterPercent)

Create a refresh policy with jitter to avoid thundering herd 创建带抖动的刷新策略以避免惊群效应

Method Details
- shouldRefresh
  
  boolean shouldRefresh(K key, long ageMillis, long ttlMillis)
  
  Determine if an entry should be refreshed 确定条目是否应该刷新
  
  Parameters:
  
  key - the cache key | 缓存键
  
  ageMillis - the age of the entry in milliseconds | 条目年龄（毫秒）
  
  ttlMillis - the configured TTL in milliseconds | 配置的 TTL（毫秒）
  
  Returns:
  
  true if the entry should be refreshed | 如果应该刷新返回 true
- onRefreshSuccess
  
  default void onRefreshSuccess(K key, V oldValue, V newValue)
  
  Called after successful refresh 刷新成功后调用
  
  Parameters:
  
  key - the cache key | 缓存键
  
  oldValue - the old value | 旧值
  
  newValue - the new value | 新值
- onRefreshFailure
  
  default void onRefreshFailure(K key, V oldValue, Throwable error)
  
  Called when refresh fails 刷新失败时调用
  
  Parameters:
  
  key - the cache key | 缓存键
  
  oldValue - the old value | 旧值
  
  error - the error | 错误
- refreshExecutor
  
  default Executor refreshExecutor()
  
  Get the refresh executor (default: common pool) 获取刷新执行器（默认: 公共池）
  
  Returns:
  
  the executor | 执行器
- percentageOfTtl
  
  static <K,V> RefreshAheadPolicy<K,V> percentageOfTtl(double percentage)
  
  Create a policy that refreshes when a percentage of TTL has elapsed 创建当 TTL 过了指定百分比时刷新的策略
  
  Type Parameters:
  
  K - the key type | 键类型
  
  V - the value type | 值类型
  
  Parameters:
  
  percentage - the percentage (0.0 to 1.0), e.g., 0.8 means refresh at 80% of TTL | 百分比（0.0 到 1.0）
  
  Returns:
  
  the refresh policy | 刷新策略
- beforeExpiration
  
  static <K,V> RefreshAheadPolicy<K,V> beforeExpiration(Duration beforeExpiration)
  
  Create a policy that refreshes a fixed duration before expiration 创建在过期前固定时间刷新的策略
  
  Type Parameters:
  
  K - the key type | 键类型
  
  V - the value type | 值类型
  
  Parameters:
  
  beforeExpiration - the duration before expiration to trigger refresh | 触发刷新的过期前时间
  
  Returns:
  
  the refresh policy | 刷新策略
- custom
  
  static <K,V> RefreshAheadPolicy<K,V> custom(RefreshAheadPolicy.RefreshPredicate<K> predicate)
  
  Create a custom refresh policy 创建自定义刷新策略
  
  Type Parameters:
  
  K - the key type | 键类型
  
  V - the value type | 值类型
  
  Parameters:
  
  predicate - the predicate to determine if refresh is needed | 判断是否需要刷新的断言
  
  Returns:
  
  the refresh policy | 刷新策略
- disabled
  
  static <K,V> RefreshAheadPolicy<K,V> disabled()
  
  Create a disabled policy (no refresh ahead) 创建禁用的策略（不提前刷新）
  
  Type Parameters:
  
  K - the key type | 键类型
  
  V - the value type | 值类型
  
  Returns:
  
  a policy that never triggers refresh | 永不触发刷新的策略
- adaptive
  
  static <K,V> RefreshAheadPolicy<K,V> adaptive(double minPercentage, double maxPercentage)
  
  Create a refresh policy with adaptive threshold based on load 创建基于负载的自适应阈值刷新策略
  Adjusts refresh threshold based on access frequency. High-traffic keys refresh earlier to ensure availability.
  
  根据访问频率调整刷新阈值。高流量的键提前刷新以确保可用性。
  
  Type Parameters:
  
  K - the key type | 键类型
  
  V - the value type | 值类型
  
  Parameters:
  
  minPercentage - minimum percentage of TTL before refresh (e.g., 0.5) | 刷新前 TTL 的最小百分比
  
  maxPercentage - maximum percentage of TTL before refresh (e.g., 0.9) | 刷新前 TTL 的最大百分比
  
  Returns:
  
  the adaptive refresh policy | 自适应刷新策略
- withJitter
  
  static <K,V> RefreshAheadPolicy<K,V> withJitter(double basePercentage, double jitterPercent)
  
  Create a refresh policy with jitter to avoid thundering herd 创建带抖动的刷新策略以避免惊群效应
  
  Type Parameters:
  
  K - the key type | 键类型
  
  V - the value type | 值类型
  
  Parameters:
  
  basePercentage - base percentage of TTL | TTL 的基础百分比
  
  jitterPercent - jitter range as percentage (e.g., 0.1 means ±10%) | 抖动范围百分比
  
  Returns:
  
  the jittered refresh policy | 带抖动的刷新策略
- or
  
  default RefreshAheadPolicy<K,V> or(RefreshAheadPolicy<K,V> other)
  
  Combine with another policy using OR logic 使用 OR 逻辑与另一个策略组合
  
  Parameters:
  
  other - the other policy | 另一个策略
  
  Returns:
  
  combined policy | 组合后的策略
- and
  
  default RefreshAheadPolicy<K,V> and(RefreshAheadPolicy<K,V> other)
  
  Combine with another policy using AND logic 使用 AND 逻辑与另一个策略组合
  
  Parameters:
  
  other - the other policy | 另一个策略
  
  Returns:
  
  combined policy | 组合后的策略

Interface RefreshAheadPolicy<K,V>

Nested Class Summary

Method Summary

Method Details

shouldRefresh

onRefreshSuccess

onRefreshFailure

refreshExecutor

percentageOfTtl

beforeExpiration

custom

disabled

adaptive

withJitter

or

and