easyfk-chronicle-map Chronicle Map

<dependency>
    <groupId>com.mcst</groupId>
    <artifactId>chronicle-map</artifactId>
</dependency>

dependencies {
    implementation 'com.mcst:chronicle-map'
}

┌─────────────────────────────────────────────────┐
│                  应用业务层                       │
│  ChronicleMapTemplate.put / get / remove         │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│  ChronicleMapManager（Map 管理器）                │
│  · 类型安全校验 · 读写锁优化 · 懒加载创建        │
│  · 类型验证缓存 · 类型化包装器缓存               │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│  Chronicle Map（堆外键值存储引擎）                │
│  · 堆外内存（Off-Heap）· 零 GC 影响             │
│  · 内存映射文件 · 持久化 / 恢复                  │
│  · 多线程并发安全 · 亚微秒级读写                 │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│  文件系统（可选持久化）                           │
│  ./chronicle-maps/mapName.dat                    │
└─────────────────────────────────────────────────┘

easyfk:
  config:
    chronicle:
      map:
        default-path: ./chronicle-maps
        default-max-entries: 100000
        default-average-key-size: 64
        default-average-value-size: 1024
        persistence-enabled: true
        maps:
          - map-name: userCache
            max-entries: 50000
            average-key-size: 32
            average-value-size: 512
            persistence-enabled: true
            key-type: java.lang.String
            value-type: java.lang.Object
          - map-name: sessionStore
            max-entries: 10000
            average-key-size: 64
            average-value-size: 2048
            persistence-enabled: true
          - map-name: counterMap
            max-entries: 1000
            key-type: java.lang.String
            value-type: java.lang.Long
            persistence-enabled: false

@Service
public class UserCacheService {

    @Autowired
    private ChronicleMapTemplate chronicleMapTemplate;

    private static final String MAP_NAME = "userCache";

    // 存储
    public void cacheUser(String userId, UserDTO user) {
        chronicleMapTemplate.put(MAP_NAME, userId, user);
    }

    // 获取
    public UserDTO getUser(String userId) {
        return (UserDTO) chronicleMapTemplate.get(MAP_NAME, userId);
    }

    // 获取（带默认值）
    public UserDTO getUserOrDefault(String userId, UserDTO defaultUser) {
        return (UserDTO) chronicleMapTemplate.getOrDefault(MAP_NAME, userId, defaultUser);
    }

    // 不存在时才存储
    public void cacheIfAbsent(String userId, UserDTO user) {
        chronicleMapTemplate.putIfAbsent(MAP_NAME, userId, user);
    }

    // 删除
    public void removeUser(String userId) {
        chronicleMapTemplate.remove(MAP_NAME, userId);
    }

    // 检查是否存在
    public boolean exists(String userId) {
        return chronicleMapTemplate.containsKey(MAP_NAME, userId);
    }

    // 获取缓存大小
    public long cacheSize() {
        return chronicleMapTemplate.size(MAP_NAME);
    }
}

// 批量存储
Map<String, Object> batch = new HashMap<>();
batch.put("user:1001", user1);
batch.put("user:1002", user2);
batch.put("user:1003", user3);
chronicleMapTemplate.putAll("userCache", batch);

// 获取所有键
Set<String> keys = chronicleMapTemplate.keySet("userCache");

// 获取所有值
Collection<Object> values = chronicleMapTemplate.values("userCache");

// 获取所有键值对
Set<Map.Entry<String, Object>> entries = chronicleMapTemplate.entrySet("userCache");

// 清空
chronicleMapTemplate.clear("userCache");

// 如果键不存在，计算并存储
Object value = chronicleMapTemplate.computeIfAbsent("configCache", "db.url",
    key -> loadConfigFromDB(key));

// 如果键存在，重新计算
chronicleMapTemplate.computeIfPresent("counterMap", "loginCount",
    (key, oldValue) -> (Long) oldValue + 1);

@Service
public class CounterService {

    @Autowired
    private ChronicleMapTemplate chronicleMapTemplate;

    private static final String MAP_NAME = "counterMap";

    // 强类型存储
    public void setCounter(String name, Long value) {
        chronicleMapTemplate.put(MAP_NAME, String.class, Long.class, name, value);
    }

    // 强类型获取
    public Long getCounter(String name) {
        return chronicleMapTemplate.get(MAP_NAME, String.class, Long.class, name);
    }

    // 强类型批量存储
    public void setCounters(Map<String, Long> counters) {
        chronicleMapTemplate.putAll(MAP_NAME, String.class, Long.class, counters);
    }

    // 强类型原子计算
    public Long incrementCounter(String name) {
        return chronicleMapTemplate.computeIfPresent(MAP_NAME, String.class, Long.class,
            name, (k, v) -> v + 1);
    }
}

@Service
public class DynamicMapService {

    @Autowired
    private ChronicleMapManager chronicleMapManager;

    // 动态创建 Map
    public void createMap(String mapName) {
        chronicleMapManager.getOrCreateMap(mapName, String.class, String.class);
    }

    // 带自定义配置创建
    public void createCustomMap(String mapName) {
        chronicleMapManager.getOrCreateMap(mapName,
            50000,   // maxEntries
            32.0,    // avgKeySize
            256.0,   // avgValueSize
            "./data/" + mapName + ".dat"  // filePath
        );
    }

    // 检查 Map 是否存在
    public boolean mapExists(String mapName) {
        return chronicleMapManager.containsMap(mapName);
    }

    // 获取所有 Map 名称
    public Set<String> listMaps() {
        return chronicleMapManager.getMapNames();
    }

    // 获取统计信息
    public String getStats(String mapName) {
        return chronicleMapManager.getMapStats(mapName);
    }

    // 移除并关闭 Map
    public void removeMap(String mapName) {
        chronicleMapManager.removeMap(mapName);
    }

    // 关闭所有 Map（应用关闭时）
    public void shutdown() {
        chronicleMapManager.closeAll();
    }
}

// 检查 Map 是否存在
boolean exists = chronicleMapTemplate.mapExists("userCache");

// 获取所有 Map 名称
Set<String> mapNames = chronicleMapTemplate.getAllMapNames();

// 获取统计信息
String stats = chronicleMapTemplate.getStats("userCache");

easyfk:
  config:
    chronicle:
      map:
        persistence-enabled: true    # 全局启用持久化
        default-path: ./chronicle-maps

easyfk:
  config:
    chronicle:
      map:
        persistence-enabled: false   # 纯内存模式

easyfk:
  config:
    chronicle:
      map:
        persistence-enabled: true
        maps:
          - map-name: importantData
            persistence-enabled: true    # 重要数据持久化
          - map-name: tempCache
            persistence-enabled: false   # 临时缓存不持久化