Class CacheSnapshot

java.lang.Object
cloud.opencode.base.cache.util.CacheSnapshot
public final class CacheSnapshot extends Object
Cache Snapshot - Utility for saving and restoring cache state to/from disk 缓存快照 - 将缓存状态保存到磁盘并从磁盘恢复的工具

Enables cache warm restart by persisting cache entries to a file and restoring them on startup. Expired entries are skipped during restore.

通过将缓存条目持久化到文件来实现缓存热重启，启动时恢复。恢复时跳过过期条目。

Features | 主要功能:

  • Save cache entries to disk - 将缓存条目保存到磁盘
  • Restore cache entries from disk - 从磁盘恢复缓存条目
  • Base64 encoding for safe serialization - Base64 编码保证安全序列化
  • Convenience methods for String caches - String 缓存的便捷方法

Usage Examples | 使用示例:

// Save a String cache
CacheSnapshot.saveStringCache(cache, Path.of("/tmp/cache.snapshot"));

// Restore a String cache
int count = CacheSnapshot.restoreStringCache(Path.of("/tmp/cache.snapshot"), cache);

// Save with custom serializers
CacheSnapshot.save(cache, path, Object::toString, Object::toString);

// Restore with custom deserializers
int count = CacheSnapshot.restore(path, cache, Function.identity(), Function.identity());

File Format | 文件格式:

# OpenCache Snapshot v1
# Created: 2026-04-03T10:00:00Z
# Entries: 1234
KEY_BASE64\tVALUE_BASE64\tTTL_REMAINING_MS

Performance | 性能特性:

  • Uses buffered I/O for efficient disk access - 使用缓冲 I/O 高效磁盘访问
  • Base64 encoding overhead: ~33% size increase - Base64 编码开销: 约 33% 大小增加
  • Save uses asMap().forEach() for streaming iteration — avoids full-copy overhead of entries() on large caches - Save 使用 asMap().forEach() 流式遍历 — 避免大缓存时 entries() 的全量拷贝开销

Security | 安全性:

  • Does NOT use Java native serialization (ObjectInputStream/ObjectOutputStream) - 不使用 Java 原生序列化
  • Thread-safe: Yes (stateless) - 线程安全: 是（无状态）
  • Null-safe: No (null keys/values not supported) - 空值安全: 否（不支持 null 键/值）
Since:
JDK 25, opencode-base-cache V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • save

      public static <K,V> void save(Cache<K,V> cache, Path path, Function<K,String> keySerializer, Function<V,String> valueSerializer) throws IOException
      Save cache entries to a file using the provided serializers. 使用提供的序列化器将缓存条目保存到文件。

      Each entry is serialized as a line with Base64-encoded key and value separated by tabs. TTL is always -1 (default TTL) because the Cache interface does not expose per-entry TTL information.

      每个条目被序列化为一行，Base64 编码的键和值用制表符分隔。 TTL 始终为 -1（默认 TTL），因为 Cache 接口不暴露单条目 TTL 信息。

      Type Parameters:
      K - the key type | 键类型
      V - the value type | 值类型
      Parameters:
      cache - the cache to snapshot | 要快照的缓存
      path - the file path to write | 要写入的文件路径
      keySerializer - function to serialize keys to strings | 键序列化函数
      valueSerializer - function to serialize values to strings | 值序列化函数
      Throws:
      IOException - if an I/O error occurs | 发生 I/O 错误时抛出

    • restore

      public static <K,V> int restore(Path path, Cache<K,V> cache, Function<String,K> keyDeserializer, Function<String,V> valueDeserializer) throws IOException
      Restore cache entries from a file. 从文件恢复缓存条目。

      Reads the snapshot file and puts each entry into the target cache. Lines with TTL of 0 are skipped (expired). Lines with TTL of -1 use the cache's default TTL.

      读取快照文件并将每个条目放入目标缓存。TTL 为 0 的行被跳过（已过期）。 TTL 为 -1 的行使用缓存的默认 TTL。

      Type Parameters:
      K - the key type | 键类型
      V - the value type | 值类型
      Parameters:
      path - the file path to read | 要读取的文件路径
      cache - the target cache | 目标缓存
      keyDeserializer - function to deserialize keys from strings | 键反序列化函数
      valueDeserializer - function to deserialize values from strings | 值反序列化函数
      Returns:
      number of entries restored | 恢复的条目数
      Throws:
      IOException - if an I/O error occurs | 发生 I/O 错误时抛出

    • saveStringCache

      public static void saveStringCache(Cache<String,String> cache, Path path) throws IOException
      Save a String-keyed, String-valued cache to a file. 将 String 键值缓存保存到文件。

      Convenience method for Cache<String, String> — uses identity serializers (strings are encoded as-is via Base64).

      Cache<String, String> 的便捷方法 — 使用恒等序列化器 （字符串通过 Base64 原样编码）。

      Parameters:
      cache - the string cache to save | 要保存的 String 缓存
      path - the file path | 文件路径
      Throws:
      IOException - if an I/O error occurs | 发生 I/O 错误时抛出

    • restoreStringCache

      public static int restoreStringCache(Path path, Cache<String,String> cache) throws IOException
      Restore a String-keyed, String-valued cache from a file. 从文件恢复 String 键值缓存。

      Convenience method for Cache<String, String> — uses identity deserializers.

      Cache<String, String> 的便捷方法 — 使用恒等反序列化器。

      Parameters:
      path - the file path | 文件路径
      cache - the target string cache | 目标 String 缓存
      Returns:
      number of entries restored | 恢复的条目数
      Throws:
      IOException - if an I/O error occurs | 发生 I/O 错误时抛出