J2cache

1. 简介

J2Cache 是 OSChina 目前正在使用的两级缓存框架（要求至少 Java 8）。第一级缓存使用内存(同时支持 Ehcache 2.x、Ehcache 3.x 和 Caffeine)，第二级缓存使用 Redis(推荐)/Memcached 。
由于大量的缓存读取会导致 L2 的网络成为整个系统的瓶颈，因此 L1 的目标是降低对 L2 的读取次数。
该缓存框架主要用于集群环境中。单机也可使用，用于避免应用重启导致的缓存冷启动后对后端业务的冲击。

J2Cache 相关文章：

J2Cache 已经有 Python 语言版本了，详情请看 https://gitee.com/ld/Py3Cache

J2Cache 从 1.3.0 版本开始支持 JGroups 和 Redis Pub/Sub 两种方式进行缓存事件的通知。在某些云平台上可能无法使用 JGroups 组播方式，可以采用 Redis 发布订阅的方式。详情请看 j2cache.properties 配置文件的说明。

视频介绍：http://v.youku.com/v_show/id_XNzAzMTY5MjUy.html

J2Cache 的两级缓存结构

L1：进程内缓存(caffeine\ehcache)
L2： Redis/Memcached 集中式缓存

1.1 数据读取

读取顺序 -> L1 -> L2 -> DB
数据更新

1 从数据库中读取最新数据，依次更新 L1 -> L2 ，发送广播清除某个缓存信息
2 接收到广播（手工清除缓存 & 一级缓存自动失效），从 L1 中清除指定的缓存信息

1.2 J2Cache 配置

配置文件位于 core/resources 目录下，包含三个文件：

j2cache.properties J2Cache 核心配置文件，可配置两级的缓存，Redis 服务器、连接池以及缓存广播的方式
caffeine.properties 如果一级缓存选用 Caffeine ，那么该文件用来配置缓存信息
ehcache.xml Ehcache 的配置文件，配置说明请参考 Ehcache 文档
ehcache3.xml Ehcache3 的配置文件，配置说明请参考 Ehcache 文档
network.xml JGroups 网络配置，如果使用 JGroups 组播的话需要这个文件，一般无需修改

实际使用过程需要将所需的配置文件复制到应用类路径中，如 WEB-INF/classes 目录。

J2Cache 运行时所需 jar 包请查看 core/pom.xml

2. J2Cache核心类

2.1 Cache

核心类：net.oschina.j2cache.Cache

Cache是基础缓存接口，定义了缓存的基本操作方法：

get() - 获取缓存数据
put() - 存储缓存数据
evict() - 删除缓存数据
clear() - 清空缓存
keys() - 获取所有键

它有两个子接口：

Level1Cache：一级缓存接口，增加了tty()和size()方法
Level2Cache：二级缓存接口，增加了对字节数组操作的方法

2.2 CacheProvider

核心类：net.oschina.j2cache.CacheProvider

CacheProvider是缓存提供者接口，负责创建和管理具体的缓存实例：

主要方法包括：

name()：返回缓存提供者的名称（如”caffeine”、”redis”等）
level()：返回缓存层级（一级或二级）
buildCache()：构建具体的缓存实例
start()：初始化缓存提供者
stop()：关闭缓存提供者

每种缓存技术（如Caffeine、Ehcache、Redis等）都有对应的实现类：

CaffeineProvider
EhCacheProvider
RedisCacheProvider
XmemcachedCacheProvider

2.3 CacheProviderHolder

核心类：net.oschina.j2cache.CacheProviderHolder

CacheProviderHolder是缓存提供者持有者，负责管理一级和二级缓存提供者：
主要职责：

管理一级和二级缓存提供者实例
根据配置初始化相应的缓存提供者
提供获取具体缓存实例的方法
协调两级缓存的操作

关键方法：

init()：初始化缓存提供者
getLevel1Cache()：获取一级缓存实例
getLevel2Cache()：获取二级缓存实例
shutdown()：关闭所有缓存提供者

2.4 CacheChannel

核心类：net.oschina.j2cache.CacheChannel

CacheChannel 是J2Cache对外提供的核心操作类，实现了两级缓存的协调工作：
主要职责：

提供面向用户的缓存操作接口
协调一级缓存和二级缓存的操作
处理缓存同步和集群通信

关键方法：

get(…) - 从缓存中获取数据(支持单个和批量)
set(…) - 设置缓存数据(支持单个和批量)
evict(String region, String…keys) - 删除缓存项
clear(String region) - 清空缓存区域
check(String region, String key) - 检查缓存在哪一级存在
regions() - 获取所有缓存区域

2.5 J2CacheBuilder

核心类：net.oschina.j2cache.J2CacheBuilder

J2CacheBuilder 是J2Cache的构建器，负责整个缓存系统的初始化：

主要职责：

初始化整个J2Cache系统
配置缓存提供者和集群策略
创建并返回CacheChannel实例

关键方法：

init(J2CacheConfig config) - 初始化构建器
getChannel() - 获取缓存操作通道
close() - 关闭缓存系统

2.6 J2Cache

核心类：net.oschina.j2cache.J2Cache

J2Cache的入口类，提供了静态方法来获取缓存通道：

主要职责：

提供全局访问点获取缓存通道
管理J2Cache实例的生命周期

关键方法：

getChannel() - 获取缓存操作通道
close() - 关闭J2Cache实例

3. 其他类

3.1 ClusterPolicy

核心类：net.oschina.j2cache.cluster.ClusterPolicy

ClusterPolicy是J2Cache集群策略的核心接口，定义了分布式环境下节点间通信的标准规范。它负责处理缓存变更的通知和同步，确保集群中各个节点的数据一致性。

主要方法：
- 连接管理方法：
  connect(Properties props, CacheProviderHolder holder) - 连接到集群
  disconnect() - 断开集群连接
- 消息发布方法：
  publish(Command cmd) - 发送消息到集群
  sendEvictCmd(String region, String…keys) - 发送清除缓存命令（默认实现）
  sendClearCmd(String region) - 发送清除整个区域命令（默认实现）
  - 本地缓存操作方法：
    evict(String region, String… keys) - 删除本地缓存条目
    clear(String region) - 清除本地整个缓存区域
  - 命令识别方法：
    isLocalCommand(Command cmd) - 判断是否为本地实例发出的命令
    handleCommand(Command cmd) - 处理接收到的命令（默认实现）

3.2 J2CacheConfig

核心类：net.oschina.j2cache.J2CacheConfig

J2CacheConfig 类是 J2Cache 框架中的核心配置类，用于管理整个缓存系统的配置信息。

J2CacheConfig 类的主要作用是存储和管理 J2Cache 的配置参数，包括：

两级缓存的配置（L1 和 L2）
缓存广播机制配置
序列化方式配置
其他相关配置参数

该类负责从配置文件中加载配置信息，并提供方法供其他组件获取这些配置。

主要字段

properties：存储所有配置属性
broadcastProperties：广播相关的配置属性
l1CacheProperties：一级缓存相关的配置属性
l2CacheProperties：二级缓存相关的配置属性
broadcast：广播策略
l1CacheName：一级缓存提供者类名
l2CacheName：二级缓存提供者类名
serialization：序列化方式
syncTtlToRedis：是否同步TTL到Redis
defaultCacheNullObject：是否默认缓存空对象

主要方法

静态初始化方法

initFromConfig(String configResource)：从资源路径加载配置
initFromConfig(File configFile)：从文件加载配置
initFromConfig(InputStream stream)：从输入流加载配置
initFromConfig(Properties properties)：从Properties对象加载配置
配置操作方法

getSubProperties(String i_prefix)：获取指定前缀的子属性
dump(PrintStream writer)：将配置信息输出到指定的打印流

J2CacheConfig 类在以下场景中被广泛使用：
- 初始化 J2Cache 时加载配置
- 在 Spring Boot Starter 中通过环境变量构建配置
- Hibernate 集成中使用
- MyBatis 缓存适配器中使用
通过 J2CacheConfig 对象，J2Cache 能够灵活地支持不同的缓存提供者、广播机制和配置方式，使得整个缓存框架具有很高的可配置性和扩展性

4. springboot-j2cache-starter

4.1 自动配置注册文件

在 Spring Boot 2 中，自动配置类通过 META-INF/spring.factories 文件注册：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
net.oschina.j2cache.autoconfigure.J2CacheAutoConfiguration,\
net.oschina.j2cache.autoconfigure.J2CacheSpringCacheAutoConfiguration,\
net.oschina.j2cache.autoconfigure.J2CacheSpringRedisAutoConfiguration

4.2 配置属性类

J2CacheConfig 类使用 @ConfigurationProperties(prefix = “j2cache”) 注解，用于绑定 application.properties 中以 j2cache 为前缀的配置项。

4.3 核心自动配置类

J2CacheAutoConfiguration 是主要的自动配置类，负责：

初始化 J2Cache 配置
创建 CacheChannel Bean
注册 SpringUtil 工具类

J2CacheSpringCacheAutoConfiguration 是专门用于支持 Spring Cache 抽象的配置类：

只有当配置 j2cache.open-spring-cache=true 时才会启用
启用 Spring 的缓存注解功能（@EnableCaching）
创建 J2CacheCacheManger 作为 Spring Cache 的管理器

J2CacheSpringRedisAutoConfiguration 是专门用于集成 Spring Data Redis 的配置类：

只有当配置 j2cache.l2-cache-open=true 时才会启用（默认启用）
配置 Redis 连接工厂（支持 Jedis 和 Lettuce）
创建 RedisTemplate 和消息监听容器
处理 Redis 的各种连接模式（单机、集群、哨兵等）

4.4 配置类执行顺序

RedisAutoConfiguration（Spring Boot 内置）

Spring Boot 自带的 Redis 自动配置类
最先执行

J2CacheSpringRedisAutoConfiguration（Redis 集成配置）

在 RedisAutoConfiguration 之后执行（@AutoConfigureAfter）
负责创建 Redis 连接相关 Bean：
- RedisConnectionFactory（支持 Jedis 和 Lettuce）
- RedisTemplate
- RedisMessageListenerContainer

J2CacheAutoConfiguration（核心配置）

在 J2CacheSpringRedisAutoConfiguration 之前执行（@AutoConfigureBefore）
负责创建核心 J2Cache Bean：
- J2CacheConfig（J2Cache 配置对象）
- CacheChannel（缓存通道，J2Cache 核心组件）
- SpringUtil（Spring 工具类）