JAD-CACHE緩存框架，使用手冊

通用緩存框架(JAD-CACHE)使用配置說明書

編 號：JAD-INFR-CACHE

版 本：1.0.1-RELEASE

擬製人：何川

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等緩存廠商，而且能夠經過配置或者在運行期間靈活禁用或啓用緩存。大體功能彙總以下：

    一、提供統一的緩存操做api；

    二、支持同時使用 EhCache、MemCache等 多種緩存實現；

    三、提供靈活的配置；

    四、須要防止緩存穿透；

    五、須要能夠靈活指定緩存存活時間；

    六、須要任意控制緩存的停用或啓用。

1.4 定義、術語及縮寫

縮寫	英文全稱	中文全稱
JAD	Java Auto Develop	java自動化開發平臺
JAD-CACHE	Cache of JAD	jad項目緩存模塊

1.5 文件修訂記錄

文件修訂記錄

版本修改記錄  （A --- 增長    M --- 修改    D --- 刪除）

當前版本	日期	修改位置 （圖、表、章節）	A/M/D	簡單描述 （緣由和修改簡介）	修改人	評審人
1.0.1-RELEASE	2017-03-12	ALL	A	創建	何川

1.6 參考

相關參考文檔：

一、寫本身的緩存框架，以同時支持ehcache、mecache及springcache註解等.docx

二、寫本身的緩存框架，JAD-CACHE架構設計篇.docx

三、JAD-CACHE緩存框架,srping集成EhCache及實現本地緩存.docx

四、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可配置的全部屬性以下表：

property	可否缺省	默認值	說明
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可配置的全部屬性以下表：

property	可否缺省	默認值	說明
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可用的屬性配置以下表：

property	可否缺省	默認值	說明
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可用的屬性配置以下表：

property	可否缺省	默認值	說明
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可用的屬性配置以下表：

property	可否缺省	默認值	說明
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經常使用的方法以下：

getInstance() 得到此類的實例（此類的構造函數已經私有化了，須要經過此方法來得到它的實例）。

init(MasterCacheManager) 初始化，這個方法系統會自動調用，開發人員無需理會

getClientNames() 得到系統中全部緩存客戶端的名稱列表

start(String) 啓動一個客戶端，參數爲客戶端名稱

stop(String) 中止一個客戶端，參數爲客戶端名稱

isStarted(String) 檢查客戶端是否啓動，參數爲客戶端名稱

4.2.2        CacheHelper經常使用api

getInstance(String) 跟據緩存名稱得到此類的實例（此類的構造函數已經私有化了，須要經過此方法來得到它的實例），參數爲須要操做的 Cache的名稱。

get(String)從緩存中讀取數，參數爲key

put(String, Serializable)往緩存中插入數據

put(String, Serializable, int) 往緩存中插入數據，並指定存活時間

evict(String)跟據key從緩存中刪除數據

clear()清空緩存數據

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

其它具體的詳細配置可參見源碼的測試用例，開發人員可跟據本身的須要來指定相應的日誌輸出級別。

更多信息，請關注本人公衆號：