?

?

?

?

?

? Sapphire Cache Framework API

??? Sapphire是一個高并發、高緩存吞吐性、高性能的Java分布式內存對象緩存系統，其具有簡單易學、方便實用等特點。它能夠用來存儲各種格式的數據，包括圖像、視頻、文件以及數據庫檢索的結果等。簡單的說就是將數據源中的數據臨時存儲于內存中，然后從內存中讀取，從而大大提高讀取速度。

?

Sapphire目前最新版本為1.1.7-beta，主要特性包含：

1.敏捷快速；

2.體系結構中立、跨平臺支持；?

3.多種緩存管理容器實現；

4.多種緩存策略（LRU、LFU、FIFO、RDM）；

5.支持緩存注解服務驅動（Annotation方式直接緩存方法）；

6.支持緩存持久化及加載虛擬機運行期數據；

7.單個緩存最大緩存容量為1gByte；

8.支持緩存容量單位設置（byte、kByte、mByte、gByte）

9.支持TCP單播集群、P2P廣播、組播集群、RMI組播集群；?

?

Cache提供的常用方法如下：
put(Object key, Object value)：Object 添加緩存數據
get(Object key)：Object 獲取緩存數據
remove(Object key)：Object 清除指定緩存數據
clear()：void 清除所有緩存數據
getElementsInSize()：long 獲取當前緩存已用元素數量
getSurplusElementsInSize(): long 獲取當前緩存剩余元素數量
getMaxElementsInSize(): long 獲取當前緩存最大元素數量
getCacheInMemory(): long 獲取當前緩存已用緩存容量
getMaxCacheInMemory(): long 獲取當前緩存最大緩存容量
getSurplusCacheInMemory():long 獲取當前緩存剩余緩存容量
cacheUseRecords(Object key): void 計算緩存使用記錄
getCacheUseRecords():HashMap 獲取緩存使用記錄
getMaxCacheInMemoryForByte(long maxCacheInMemory,
String capacityUnit): long 計算當前緩存的最大字節緩存容量

5.使用Sapphire緩存缺省數據類型
缺省情況下Sapphire可以為您緩存的數據類型為如下3類：
基本數據類型；
數組類型；
String類型；

使用Sapphire緩存缺省數據類型實現：
/* 緩存基本數據類型 */
cache.put("byte", 1);
cache.put("short", 10);
cache.put("int", 100);
cache.put("long", 1000L);
cache.put("float", 1.5);
cache.put("double", 10.5D);
cache.put("char", 'A');
cache.put("boolean", true);

/* 緩存數組數據類型 */
cache.put("byte[]", new byte[100]);

/* 緩存String數據類型 */
cache.put("String", "Sapphire Cache");

6.使用Sapphire緩存復合數據類型
缺省情況下Sapphire并沒有提供對復合數據類型的支持，但您可以將您需要緩存的復合對象實現Sapphire為您提供的CacheSerializable接口（該接口為標記接口，無需任何實現）。一旦您的復合對象實現了該接口，Sapphire便會允許緩存您所指定的復合對象，除了可以實現CacheSerializable接口，Sapphire仍然允許您實現JDK原生的Serializable接口。
至于復合數據類型為什么需要實現CacheSerializable接口或者實現Serializable接口Sapphire才允許將其緩存呢？其實Sapphire在對您的數據進行緩存之前需要將所有數據進行序列化處理，以便計算當前所需緩存的數據所占緩存容量的內存大小。
使用Sapphire緩存復合數據類型實現：
class SaveObject implements CacheSerializable
{
//...
}

/* 初始化Sapphire容器方式 */
CacheManager cacheManager = new SapphireCacheManager();

/* 獲取緩存實例 */
Cache cache = cacheManager.getCache("defaultCache");

/* 緩存復合數據類型 */
cache.put("object", new SaveObject());
System.out.println(cache.get("object") instanceof CacheSerializable);

注意：
如果您在使用Sapphire為您緩存復合對象時并沒有將所需緩存的數據實現CacheSerializable接口或者Serializable接口，Sapphire將會拋出java.io.NotSerializableException異常信息。

7.啟動緩存注解服務驅動
通過Sapphire的配置文件我們可以觀察到<service:annotation-driven>標簽。該標簽主要用作于開啟緩存注解服務驅動，其中包含有一個auto屬性，該屬性所允許的參數范圍為“true”與“false”。如果您將auto屬性設置為“true”，則意味著您將成功開啟Sapphire的緩存注解服務驅動服務，否則意味著該服務的狀態為關閉狀態。
至于開啟Sapphire的緩存注解服務驅動有何用處，想必這是您最為關心的問題。其實不難發現在很多復雜應用的情況下，我們經常需要緩存具體的方法返回結果（比如服務層與持久層），面對這種情況雖然我們可以使用Cache對象的put方法進行數據緩存，但這并不靈活。所以Sapphire將為您提供了一個基于注解方式的方法返回值緩存技術，這便是剛才我們所提到的緩存注解服務。
位于org.sapphire.cache.annotation包下的@CacheService類型正是我們即將使用到的方法返回值緩存技術的實現。
緩存注解服務驅動實例：
此處省略導包過程…
public class SapphireCacheTest extends TestCase
{
/**
* @param args
*/
public static void main(String[] args) throws Exception
{
/* 初始化Sapphire容器方式 */
CacheManager cacheManager = new SapphireCacheManager();

/* 獲取緩存實例 */
Cache cache = cacheManager.getCache("defaultCache");
Element element1 = new Element(SaveObject.class.getName(),
"testService1", cache);
element1.put(26);
System.out.println("age: " + cache.get("age"));
Element element2 = new Element(SaveObject.class.getName(),
"testService2", cache);
element2.put(1, "JohnGao");
System.out.println("UserBean: " + cache.get("info"));
}
}

此處省略導包過程…
public class SaveObject implements CacheSerializable
{
@CacheService(cacheElementKey = "age")
public int testService1(int age)
{
return age;
}

@CacheService(cacheElementKey = "info")
public Object testService2(int userId, String userName)
{
class InfoBean implements CacheSerializable
{
int userId;
String userName;
}
InfoBean info = new InfoBean();
info.userId = userId;
info.userName = userName;
return info;
}
}

在您使用Sapphire為您提供的緩存注解服務器時，您務必先找到Sapphire的配置文件中的<service:annotation-driven>標簽，并將該標簽的auto屬性設置為“true”則意味著注解服務成功開啟。接著您便可以通過@CacheService(cacheElementKey = "age")的注解方式對所需緩存的方法進行標注。這里需要提醒一下@CacheService中需要設置一個cacheElementKey的屬性，該屬性所代表的是緩存Key。
當您成功的在方法前添加@CacheService標注后，仍然還需要使用到一個類型，那便是Element類型。該類型作為Sapphire的緩存元素類型，在使用緩存注解服務的時候您必須使用它才能夠對您的方法返回值進行動態緩存。
Element提供的常用方法如下：
Element(String serviceClass, String serviceMethod,
Cache cache) 構造函數（緩存類型名稱、緩存方法名稱、Cache實例）
put(Object... params)：void 添加服務參數
cacheParam(Object... params)：void 緩存服務參數

注意：
如果您并沒有開啟Sapphire的緩存注解服務便使用時，Sapphire將會拋出org.sapphire.cache.
exception.CacheServiceException異常。

8.設置緩存所能存儲的最大元素數量
Sapphire在緩存管理上為您提供了更為靈活的緩存管理方式，但首先您應該先了解Sapphire到底是如何對緩存進行管理的。
通過Sapphire的配置文件我們可以在<cache/>標簽中找到一個名為maxElementsInSize的屬性，該屬性用于定義單個緩存所允許存放的最大緩存元素數，假設您將maxElementsInSize屬性設置為10，那么您的緩存實例將只允許緩存10個數據元素。
一旦您所定義的maxElementsInSize溢出，Sapphire將會拋org.sapphire.cache.exception.
CacheElementsException異常。

9.設置緩存所能存儲的最大緩存容量
Sapphire作為一個高效的緩存Framework，單個緩存允許您存儲高達1Gbyte的緩存數據。當然Sapphire的緩存容量與實際的物理內存與VM內存精密相關，也就是說如果您希望將Sapphire的單個緩存容量設置為1GByte，那么你需要觀察您的實際物理內存及VM內存是否允許，否則Sapphire將會拋出java.lang.OutOfMemoryError異常。
通過Sapphire的配置文件我們可以在<cache/>標簽中找到2個名為maxCacheInMemory和capacityUnit的屬性，其中maxCacheInMemory屬性用于設置您所定義的緩存容量大小，而maxCacheInMemory則用于定義您的緩存容量單位，假設maxCacheInMemory定義為“10”，capacityUnit定義為“mByte”，那么也就是說您則定義了一個緩存容量為10mByte的單個緩存實例。一旦您所定義的maxCacheInMemory溢出，Sapphire將會拋出org.sapphire.cache.exception.
OutOfCacheError異常。
在程序中您可以通過Cache類型提供的一些緩存容量及元素檢測方法來觀測您具體的緩存容量開銷。
觀測緩存容量開銷實例：
/* 初始化Sapphire緩存管理容器 */
CacheManager cacheManager = new SapphireCacheManager();

/* 獲取緩存實例 */
Cache cache = cacheManager.getCache("defaultCache");

/* 添加緩存元素 */
cache.put("key", new byte[100]);
System.out.println("最大緩存元素長度：" + cache.getMaxElementsInSize());
System.out.println("當前緩存元素長度：" + cache.getElementsInSize());
System.out.println("剩余緩存元素長度：" + cache.getSurplusElementsInSize());
System.out.println("最大緩存容量：" + cache.getMaxCacheInMemory());
System.out.println("當前緩存容量：" + cache.getCacheInMemory());
System.out.println("剩余緩存容量：" + cache.getSurplusCacheInMemory());

注意：
如果最大緩存元素長度<=當前緩存元素長度時，剩余緩存元素長度則為“-1”。如果當前緩存容量>最大緩存容量時，剩余緩存容量則為“-1”。

10.緩存持久化
在您使用Sapphire緩存數據時，極有可能會出現maxElementsInSize溢出及maxCacheInMemory溢出。但這些溢出的數據可能恰恰是較為重要且不希望丟失的數據，這個時候該怎么辦呢？值得慶幸的是Sapphire為您帶來了高效的緩存持久化技術，也就是說您可以通過Sapphire的配置文件找到<cache/>標簽的overflowToDisk屬性，并設置為“true”時，那么一旦maxElementsInSize或者maxCacheInMemory溢出時，其溢出的數據并不會直接丟失，Sapphire則將會為您將這一部分溢出的數據持久化于本地進行存儲，以便于您繼續使用。
如果您希望使用Sapphire為您提供的緩存持久化技術，那么您不僅僅需要將Sapphire配置文件中得overflowToDisk屬性設置為“true”，您還需要設置<diskStore>標簽中得path、diskEternal、timeToRemoveSeconds等3個屬性。path屬性缺省為“java.io.tmpdir”，也就是說一旦出現maxElementsInSize或者maxCacheInMemory溢出時，Sapphire會將溢出數據緩存于操作系統的臨時目錄（不同的操作系統臨時目錄不同）中進行存儲，存儲格式為SAPPHIRE_CACHE.data。
除了path屬性外，<diskStore>標簽中的另外2個屬性diskEternal和timeToRemoveSeconds則將滿足您更多的需求。如果您希望您所持久化的緩存數據是永遠有效的，則需要將diskEternal屬性設置為“true”，這樣一來持久化于本地的緩存將永不失效。如果您將其設置為“false”時，則意味著timeToRemoveSeconds屬性所定義的內容將影響到持久化緩存的失效周期，假設您將timeToRemoveSeconds屬性定義為“10”，當10秒以后，Sapphire的回收器將會對持久化緩存進行回收。

11.加載虛擬機重啟期數據
當您成功將緩存進行持久化后，Sapphire為您提供了一種持久化讀取機制來加載虛擬機重啟期數據。當然您需要將Sapphire配置文件中的diskPersistent屬性設置為“true”
這里有一點您需要稍加注意，如果您在Sapphire的配置文件中設置的maxElementsInSize或者maxCacheInMemory屬性不再重啟期數據的范圍內，也就是說Sapphire仍然會將其認為溢出，導致重復緩存持久化。

12.緩存回收策略
Sapphire為您提供有3種緩存回收策略，分別為：LRU、LFU、RMD。
LRU（最少使用, Least Recently Used）將會根據您對緩存元素的實際使用來動態收回緩存元素，使用次數最少的緩存元素則優先被Sapphire回收器進行回收，當然您需要通過Sapphire的配置文件找到<cache>標簽并設置timeToLiveSeconds屬性，該屬性主要用于設置緩存的失效周期，單位為秒。假設您將timeToLiveSeconds屬性設置為“10”，則意味著10秒以后Sapphire回收器將會按照cacheCleanupPolicy屬性所定義的回收策略對緩存進行動態回收。LFU和RMD等回收策略也是經常較為適用的，但一般來說我們推薦您使用LRU緩存回收策略。

注意：
如果您在<cache>標簽中將eternal屬性設置為“true”時，則意味著您的緩存為永不失效，同樣cacheCleanupPolicy則也就意味著失效。

13.分布式緩存——TCP集群配置模式
Sapphire為您提供了3種類型的分布式緩存機制，但Sapphire推薦您使用TCP集群為首選。因為該分布式緩存的實現方式為TCP單播機制，無論是安全性、正確性、穩定性，哪怕是效率上都是較為優秀的。
如果您希望使用TCP集群配置模式的方式來實現緩存共享，那么首先您需要在Sapphire的配置文件中添加TCP集群配置。
您可以使用Sapphire為您提供的<distributedCacheManagerFactory>標簽，該標簽中一共包含了3個屬性，分別是：class、serverHost以及serverPort。其中class用于指定集群類型，serverHost屬性用于指定集群地址，serverPort屬性用于指定集群端口。
假設您已經成功配置TCP集群后，您還需在<cache>標簽中添加<distributedCacheListener>子標簽，該標簽用于啟動緩存復制監聽，并包含一個名為replicateCache的屬性，如果您將其設置為“true”則意味著您允許緩存實例實現緩存共享，否則將意味著拒絕緩存共享。
TCP集群配置示例：
<!-- 緩存注解服務驅動 -->
<service:annotation-driven auto="true" />

<!-- 緩存持久化全局配置 -->
<diskStore path="java.io.tmpdir" diskEternal="false"
timeToRemoveSeconds="60" />

<!-- TCP集群配置模式 -->
<distributedCacheManagerFactory
class="org.sapphire.cache.distributed.tcp.TcpDistributedCacheManagerFactory" serverHost="127.0.0.1" serverPort="30051" />

<!-- 缺省緩存配置 -->
<cache name="defaultCache" eternal="false" maxElementsInSize="100"
maxCacheInMemory="1" capacityUnit="mByte" overflowToDisk="true"
diskPersistent="false" timeToLiveSeconds="60" cacheCleanupPolicy="LRU">
<!-- 啟動緩存復制監聽 -->
<distributedCacheListener replicateCache="true" />
</cache>

通過上述示例，您可以發現< distributedCacheManagerFactory >標簽中的class屬性其值為一個TcpDistributedCacheManagerFactory類型(位于org.sapphire.cache.distributed.tcp包下)。該類型作用于搭建一個穩定且高性能的TCP分布式緩存服務器。
使用Sapphire來為您實現分布式緩存是一件及其簡單的事情，只要您在Sapphire的配置文件中啟用了TCP集群配置模式，并成功開啟了緩存復制監聽，那么就無需您在做任何操作，便可實現分布式緩存共享。接下來您可以通過一段簡單的測試代碼來實現Sapphire為您提供的基于TCP集群配置模式的分布式緩存。
分布式緩存示例：
/* 初始化Sapphire緩存管理容器 */
CacheManager cacheManager = new SapphireCacheManager();

/* 獲取緩存實例 */
Cache cache = cacheManager.getCache("defaultCache");
while(true)
{
cache.put("cacheKey", "cacheValue");
System.out.println(cache.get("key"));
Thread.sleep(1000);
}

上述程序一旦運行后，Sapphire便會成功開啟TCP緩存服務器，啟動緩存服務，并成功的實現緩存共享。但這個時候您可能會覺得奇怪，因為您并沒有使用客戶端對TCP緩存服務器進行連接，為什么您卻可以獲取共享后的緩存？其實這是因為在缺省環境下Sapphire的TCP緩存服務器既是服務端又是客戶端，能夠自身實現緩存共享。
如果您的網絡中有其余的節點需要共享緩存信息，那么您便可以將< distributedCacheManagerFactory >標簽中的class屬性的值更改為org.sapphire.cache.distributed.tcp. TcpDistributedCacheConnection即可，該類型為TCP集群連接類型。

注意：
如果程序中，您并沒有成功啟動TCP集群配置模式，而直接為class屬性去配置TcpDistributedCacheConnection類型，這個時候Sapphire則會拋出org.sapphire.cache.exception.
TcpCacheDistributedException異常。
還有一點您需要注意，假設您程序中有多個緩存實例都需要實現緩存共享時，您可以在Sapphire配置文件中為需要實現緩存共享的緩存類型開啟緩存復制監聽即可。

?

Sapphire Cache 1.1.7（附bata版本）