JAD-CACHE缓存框架，使用手册

[b]通用缓存框架(JAD-CACHE)[/b][b]使用配置说明书[/b]
[b]编 号：JAD-INFR-CACHE[/b]
[b]版 本：1.0.1-RELEASE[/b]
[b]拟制人：何川[/b]

1 前言

1.1 本文档目的

本文档是开源项目JAD-CACEH的标准使用手册。

1.2 关于JAD

JAD是本人跟据自己对技术的学习和理解，利用业余时间开发的一个基础架构项目，旨在为程序员提供一个高效的自动化开发平台，它涉及互联网JAVA后台技术基础架构的方方面面，比如持久化技术，比如缓存，比如分布式远程调用与微服务等等。

目前项目已经在开源中国码云平台上开源，代码地址：

https://git.oschina.net/457049726/jad-cache

1.3 关于JAD-CACEH

因为JAD项目过于庞大，很多功能目前还没有完善。现决定先将其中做的比较完整的缓存模块单独从原项目中分离出来，成为一个独立的开源项目。

JAD-CACHE是对Spring3的缓存模块的简单扩展，支持Spring3缓存的所有注解，同时提供一些缓存操作的api，使开发人员以编码的方式操作缓存。

JAD-CACHE能方便快速的集成EhCache、MemCache等缓存厂商，并且可以通过配置或者在运行期间灵活禁用或启用缓存。大致功能汇总如下：

1、提供统一的缓存操作api；

2、支持同时使用 EhCache、MemCache等 多种缓存实现；

3、提供灵活的配置；

4、需要防止缓存穿透；

5、需要可以灵活指定缓存存活时间；

6、需要任意控制缓存的停用或启用。

1.4 定义、术语及缩写

[b]缩写[/b]	[b]英文全称[/b]	[b]中文全称[/b]
JAD	Java Auto Develop	java自动化开发平台
JAD-CACHE	Cache of JAD	jad项目缓存模块

1.5 文件修订记录

[b]文件修订记录[/b]
[b]版本修改记录[/b] （A --- 增加 M --- 修改 D --- 删除）

[b]当前版本[/b]	[b]日期[/b]	[b]修改位置[/b] [b]（图、表、章节）[/b]	[b]A/M/D[/b]	[b]简单描述[/b] [b]（原因和修改简介）[/b]	[b]修改人[/b]	[b]评审人[/b]
1.0.1-RELEASE	2017-03-12	ALL	A	建立	何川

1.6 参考

相关参考文档：

1、写自己的缓存框架，以同时支持ehcache、mecache及springcache注解等.docx

2、写自己的缓存框架，JAD-CACHE架构设计篇.docx

3、JAD-CACHE缓存框架,srping集成EhCache及实现本地缓存.docx

4、JAD-CACHE缓存框架,srping整合MemCache.docx

2 JAD-CACHE源码介绍与集成

JAD-CACHE目前暂时只支持Map本地缓存与EhCache以及MemCache三种，开发人员可以单独使用其中一种，也可以同时使用这几种。

JAD-CACHE是典型的Maven项目，下分三个子模块jad-cache-api、jad-cache-ehcache、jad-cache-memcache。其中jad-cache-api为公用部分及相关api，jad-cache-ehcache为与Ehcache的集成模块，jad-cache-memcache为与memcache的集成模块。

开发人员在将本框架集成到项目中时，可以选择性的使用自己想集成的缓存实现，如果只使用Map本地缓存，就加入以下依赖：

<dependency>
<groupId>com.jad.infr</groupId>
<artifactId>jad-cache-api</artifactId>
<version>1.0.1-RELEASE</version>
</dependency>

如果你想用ehcache缓存，就用加入以下依赖：

<dependency>
<groupId>com.jad.infr</groupId>
<artifactId>jad-cache-ehcache</artifactId>
<version>1.0.1-RELEASE</version>
</dependency>

如果用memcache，就用以下依赖

<dependency>
<groupId>com.jad.infr</groupId>
<artifactId>jad-cache-memcache</artifactId>
<version>1.0.1-RELEASE</version>
</dependency>

提示：用ehcache或memcahce时，jad-cache-ehcache或jad-cache-memcache会自动把它相关依赖添加进来（包括本框架的jad-cache-api），用户无须再额外配置。

3 配置手册

配置的方式跟Spring Cache原来的配置有所不同，但都需要配置用于Srping解析注解的标签< cache:annotation-driven/>。

大致配置思路是：

1、配置< cache:annotation-driven/>

2、配置一个CacheClientManager类型的Bean指定一个客户端管理器

3、配置一个或多个CacheClient类型的Bean作为受CacheClientManager管理的客户端实例。

注意：在配置CacheClient后，应用启动时，框架会自动注入具体缓存厂商相关的CacheManager实例，所以开发人员无需再配置CacheManager。

上述三步现分三节单独说明，如下：

3.1 < cache:annotation-driven/>配置

< cache:annotation-driven/>标签的配置，与Spring原来的的cache配置一模一样，但本框架提供一另一个KeyGenerator（com.jad.cache.common.SimpleCacheKeyGenerator）用以取代原来的KeyGenerator，推荐配置如下：

<cache:annotation-driven key-generator="keyGenerator"/>
<bean id="keyGenerator" class="com.jad.cache.common.SimpleCacheKeyGenerator" />

3.2 CacheClientManager配置

如果项目只使用一种缓存厂商，比如只使用EhCache或只使用MemCache，建议使用单客户端管理器com.jad.cache.common.impl.SingleClientManager，如果想在同一项目中同时使用EhCache和MemCache，或者要两在逻辑上把某些缓存归一类而另一些缓存归为另一类分别被不同Client控制的话，可以使用多客户端管理器com.jad.cache.common.impl.MultiClientManager。

3.2.1 单客户端管理器SingleClientManager配置

单客户端管理器的实现类是SingleClientManager，最简单的配置如下所示:

<bean id="cacheClientManager" class="com.jad.cache.common.impl.SingleClientManager">
<property name="cacheClient" ref="ehcacheClient" />

</bean>

这里的bean的id可以随意指定，但必须有一个cacheClient属性，指向一个CacheClient类型的bean的id，关于CacheClient的配置，在下一节有说明。

在这个bean中还可以配置一些全局属性，作为所有缓存的全局默认配置，SingleClientManager可配置的所有属性如下表：

[b]property[/b]	[b]能否缺省[/b]	[b]默认值[/b]	[b]说明[/b]
cacheClient	否		指定它所管理的CacheCleint
defActivityTime	能	600	必须为整数，默认存活时间,大于0是才有效
allowNullValues	能	true	boolean类型，表示能否缓存空值
autoCreateCache	能	true	boolean类型，表示能否自动创建缓存

3.2.2 多客户端管理器MultiClientManager配置

多客户端管理器的实现类是MultiClientManager，最简单的配置如下所示:

<bean id="cacheClientManager" class="com.jad.cache.common.impl.MultiClientManager"> <property name="defCacheClientName" value="localCacheClient" />
<property name="cacheClientList">
<list>
<ref bean="ehcacheClient"/>
<ref bean="localCacheClient"/>
</list>
</property>
</bean>

与单客户端管理器SingleClientManager不同的是，需要指一个List类型的cacheClientList属性，以指定它能管理的所有的Client列表，同时需要指定一个默认的默户端，以便自动创建缓存时，用哪个Client。

MultiClientManager可配置的所有属性如下表：

[b]property[/b]	[b]能否缺省[/b]	[b]默认值[/b]	[b]说明[/b]
cacheClientList	否		list类型，配置可管理的Client列表
defActivityTime	能	600	必须为整数，默认存活时间,大于0是才有效
allowNullValues	能	true	boolean类型，表示能否缓存空值
autoCreateCache	能	true	boolean类型，表示能否自动创建缓存
defCacheClientName	能	defCacheClient	defCacheClientName的作用是：如果autoCreateCache参数为true系统在自动缓存时使用的Client。比如如果用户同时使用EhCache和MemCache时，可以通过这个参数指定EhCache作为默认的客户端。这样，如果没有在ehcache.xml或memcache.xml中配置某个Cache时而又要使用它时，则自动在ehcache中创建。

3.3 CacheClient配置

本框架目前暂时只支持Map本地缓存与EhCache以及MemCache三种，所有只能配置这三种类型的CacheClient，如下：

3.3.1 内置本地缓存客户端配置

内置本地缓存是用Map实例，线程安全，但因为跟应用使用同一块堆内存，缓存数据量过大时可能会溢出，请谨慎使用

本地缓存客户端的实现类是：SimpleLocalCacheClient，示例如下：

<bean id="localCacheClient" class="com.jad.cache.common.impl.SimpleLocalCacheClient">

<property name="clientName" value="localCacheClient" />

</bean>

以上配置中的clientName属性表示此CacheClient实例的名称，它是可以缺省的，缺省配置时，与此beanr的id相同。

CacheClient配置好了后，需要将此bean的id配置到上一节CacheClientManager的Bean的cacheClient或cacheClientList属性中，以便可以被CacheClientManager管理。

SimpleLocalCacheClient可用的属性配置如下表：

[b]property[/b]	[b]能否缺省[/b]	[b]默认值[/b]	[b]说明[/b]
clientName	能	默认值它对应Bean的id属性	表示指client的名字，当有多个CacheClient实例时，些属性不能重复
defActivityTime	能	默认值同对应的CacheClientManger同名属性	必须为整数，默认存活时间,大于0是才有效
allowNullValues	能	默认值同对应的CacheClientManger同名属性	boolean类型，表示它控制的Cache实例能否缓存空值
autoCreateCache	能	默认值同对应的CacheClientManger同名属性	boolean类型，表示此客户端能否自动创建Cache实例
autoStart	能	true	是否自动启动，为true时，在此bean被初始化时自动启动
cacheNames	能	缺省为空列表	如果缺省，在单客户端管理器的情况下，所有Cache实例全部被这唯的CacheClient实例管理。在多客户端管理器的情况，如果此客户端为默认客户端，则用它自动创建缓存实例并管理它，否则它不起任何作用。

3.3.2 EhCache缓存客户端配置

EhCache缓存客户端的实现类是：EhcacheClient，示例如下：

<bean id="ehcacheClient" class=" com.jad.cache.ehcache.EhcacheClient">

</bean>

EhcacheClient可用的属性配置如下表：

[b]property[/b]	[b]能否缺省[/b]	[b]默认值[/b]	[b]说明[/b]
configFile	能	ehcache.xml	ehcache配置文件名
clientName	能	默认值它对应Bean的id属性	表示指client的名字，当有多个CacheClient实例时，些属性不能重复
defActivityTime	能	默认值同对应的CacheClientManger同名属性	必须为整数，默认存活时间,大于0是才有效
allowNullValues	能	默认值同对应的CacheClientManger同名属性	boolean类型，表示它控制的Cache实例能否缓存空值
autoCreateCache	能	默认值同对应的CacheClientManger同名属性	boolean类型，表示此客户端能否自动创建Cache实例
autoStart	能	true	是否自动启动，为true时，在此bean被初始化时自动启动
cacheNames	能	缺省为空列表	如果缺省，在单客户端管理器的情况下，所有Cache实例全部被这唯的CacheClient实例管理。在多客户端管理器的情况，如果此客户端为默认客户端，则用它自动创建缓存实例并管理它，否则它不起任何作用。

说明：从上表中可看出，EhcacheClient可用的属性配置同上节的SimpleLocalCacheClient可用的属性配置其乎一样，唯一不同的是多了一个configFile属性，以指定EhCache使用的配置文件。

3.3.3 MemCache缓存客户端配置

MemCache缓存客户端的实现类是：MemCacheClient，示例如下：

<bean id="memcacheClient" class=" com.jad.cache.memcache.MemCacheClient">

<property name="masterCacheName" value="masterCache2" />

</bean>

EhcacheClient可用的属性配置如下表：

[b]property[/b]	[b]能否缺省[/b]	[b]默认值[/b]	[b]说明[/b]
configFile	能	memcache.xml	memcache配置文件名
clientName	能	默认值它对应Bean的id属性	表示指client的名字，当有多个CacheClient实例时，些属性不能重复
defActivityTime	能	默认值同对应的CacheClientManger同名属性	必须为整数，默认存活时间,大于0是才有效
allowNullValues	能	默认值同对应的CacheClientManger同名属性	boolean类型，表示它控制的Cache实例能否缓存空值
autoCreateCache	能	默认值同对应的CacheClientManger同名属性	boolean类型，表示此客户端能否自动创建Cache实例
autoStart	能	true	是否自动启动，为true时，在此bean被初始化时自动启动
cacheNames	能	缺省为空列表	如果缺省，在单客户端管理器的情况下，所有Cache实例全部被这唯的CacheClient实例管理。在多客户端管理器的情况，如果此客户端为默认客户端，则用它自动创建缓存实例并管理它，否则它不起任何作用。
masterCacheName	能	masterCache	指定memcache.xml配置文件中的一个client的name作为主要的Cache，在autoCreateCache及multiplexMasterCache同时为true时有效。
onlyLocal	能	false	是否仅使用本地缓存。MemCache自身有一个本地缓存实现，如果当前MemCache服务器还没有准备好，可以暂时使用它自带的本地缓存。
multiplexMasterCache	能	true	是否复用主缓存。
responseStatInterval	能	0	默认不进行响应统计。

上表中红色部分是MemCache中特有的属性，其具体作用可参本档附带的与MemCache集成相关的文档。

3.4 常用配置案例

本框架的配置总体上比较简单，但是比较灵活，而且很多参数都可以缺省配置，以下跟据不同的业务场景提供了几种极简的默认配置，开发人员可以在这个基础上进行配置。

3.4.1 项目中只使用EhCache的配置

<cache:annotation-driven key-generator="keyGenerator"/>
<bean id="keyGenerator" class="com.jad.cache.common.SimpleCacheKeyGenerator" />

<bean id="cacheClientManager" class="com.jad.cache.common.impl.SingleClientManager">
<property name="cacheClient" ref="ehcacheClient" />

</bean>

<bean id="ehcacheClient" class=" com.jad.cache.ehcache.EhcacheClient">

</bean>

3.4.2 项目中只使用MemCache的配置

<cache:annotation-driven key-generator="keyGenerator"/>
<bean id="keyGenerator" class="com.jad.cache.common.SimpleCacheKeyGenerator" />

<bean id="cacheClientManager" class="com.jad.cache.common.impl.SingleClientManager">
<property name="cacheClient" ref=" memcacheClient" />

</bean>

<bean id="memcacheClient" class=" com.jad.cache.memcache.MemCacheClient">

</bean>

3.4.3 项目中同时使用EhCache和MemCache的配置

<cache:annotation-driven key-generator="keyGenerator"/>
<bean id="keyGenerator" class="com.jad.cache.common.SimpleCacheKeyGenerator" />

<bean id="cacheClientManager" class="com.jad.cache.common.impl.MultiClientManager"> <property name="defCacheClientName" value="ehcacheClient" />
<property name="cacheClientList">
<list>
<ref bean="ehcacheClient"/>
<ref bean="memcacheClient"/>
</list>
</property>
</bean>

<bean id="ehcacheClient" class=" com.jad.cache.ehcache.EhcacheClient">

<property name="cacheNames">
<set>
<value>ehCache1</value>
<value>ehCache2</value>
</set>
</property>

</bean>

<bean id="memcacheClient" class=" com.jad.cache.memcache.MemCacheClient">

<property name="masterCacheName" value="memCache1" />

<property name="cacheNames">
<set>
<value>memCache1</value>
<value>memCache2</value>
</set>
</property>

</bean>

4 基本使用

4.1 注解方式

注解方式跟使用SpringCache自身的缓存注解方式一模一样，这里不再介绍。

4.2 api方式

本框架两个两个类作为开放的操作缓存的api，分别是：

com.jad.cache.common.api.CacheClientHelper和com.jad.cache.common.api.CacheHelper

其中CacheClientHelper类操作缓存客户端实例的启停，CacheHelper类可以从给定名称的Cache中读取缓存数据。

4.2.1 CacheClientHelper常用api

CacheClientHelper常用的方法如下：

[b]getInstance() [/b]获得此类的实例（此类的构造函数已经私有化了，需要通过此方法来获得它的实例）。

[b]init(MasterCacheManager) [/b]初始化，这个方法系统会自动调用，开发人员无需理会

[b]getClientNames() [/b]获得系统中所有缓存客户端的名称列表

[b]start(String) [/b]启动一个客户端，参数为客户端名称

[b]stop(String) [/b]停止一个客户端，参数为客户端名称

[b]isStarted(String) [/b]检查客户端是否启动，参数为客户端名称

4.2.2 CacheHelper常用api

[b]getInstance(String) [/b]跟据缓存名称获得此类的实例（此类的构造函数已经私有化了，需要通过此方法来获得它的实例），参数为需要操作的 Cache的名称。

[b]get(String)[/b]从缓存中读取数，参数为key

[b]put(String, Serializable)[/b]往缓存中插入数据

[b]put(String, Serializable, int) [/b]往缓存中插入数据，并指定存活时间

[b]evict(String)[/b]跟据key从缓存中删除数据

[b]clear()[/b]清空缓存数据

5 单元测试和日志输出配置

本框架源码中每个模块都有对应的单元测试类，代码在src/test/java下面，配置在src/test/resources。本人是通过testng进行测试的，建议开发人员安装testng插件进行测试。

本框架采用log4j输出日志，配置如下：

#阿里memcache

log4j.logger.com.alisoft.xplatform.asf.cache=ERROR
#ehcache

log4j.logger.net.sf.ehcache=ERROR

以上两行分别是阿里memcache 客户端中的日志配置以及ehcache的配置

跟本框架相关的日志配置如下

#jad-cache-api

log4j.logger.com.jad.cache.common=DEBUG

#jad-cache-ehcache

log4j.logger.com.jad.cache.ehcache=DEBUG

#jad-cache-memcache

log4j.logger.com.jad.cache.memcache=DEBUG

其它具体的详细配置可参见源码的测试用例，开发人员可跟据自己的需要来指定相应的日志输出级别。
更多信息，请关注本人公众号：