Ehcache 3.7文檔—基礎篇—GettingStarted

爲了使用Ehcache，你須要配置CacheManager和Cache，有兩種方式能夠配置java編程配置或者XML文件配置

一. 經過java編程配置

 

CacheManager cacheManager = CacheManagerBuilder.newCacheManagerBuilder() (1) .withCache("preConfigured", CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(10))) (2) .build(); (3) cacheManager.init(); (4) Cache<Long, String> preConfigured = cacheManager.getCache("preConfigured", Long.class, String.class); (5) Cache<Long, String> myCache = cacheManager.createCache("myCache", (6) CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(10))); myCache.put(1L, "da one!"); (7) String value = myCache.get(1L);(8) cacheManager.removeCache("preConfigured"); (9) cacheManager.close();(10)

 

(1). 這個靜態方法org.ehcache.config.builders.CacheManagerBuilder.newCacheManagerBuilder返回一個新的org.ehcache.config.builders.CacheManagerBuilder實例。

(2). 經過使用CacheManagerBuilder去定義一個名爲"preConfigured"的Cache，當cacheManager.build()被調用時這個Cache纔會被真正的建立。第一個String參數是Cache的名字，用來從CacheManager中獲取Cache的，第二個參數org.ehcache.config.CacheConfiguration是用來配置Cache的，咱們使用靜態方法newCacheConfigurationBuilder()來建立一個默認的配置。

(3). 最後調用build()返回一個CacheManager實例，可是該實例尚未初始化。

(4). 在使用CacheManager以前須要初始化，有兩種方法，一種是調用CacheManager.init()，或者是在調用CacheManagerBuilder.build(boolean init)時使用帶參數的方法而且設置成true。

(5). 向CacheManager傳入cache name，keyType，valueType來獲取一個cache。例如爲了獲取在第二步定義的cache你須要這樣設置alias="preConfigured", keyType=Long.class and valueType=String.class，爲了type-safety咱們要求兩個參數keyType和valueType都傳入。若是咱們設置的不對，CacheManager會盡早地拋出ClassCastException異常，這樣能夠防止Cache被隨機類型污染。


(6). CacheManager能夠建立一個新的Cache，像步驟二那樣，他須要傳入一個Cache名和一個Cache配置。經過CacheManager.getCache方法能夠獲取到已經初始化以後的Cache實例。

(7). 如今新添加的cache能夠用來儲存entries，entries包含了key-value的鍵值對。put方法的第一個參數是key，第二個參數是value，key和value的類型必定要和CacheConfiguration中定義的同樣，除此以外這個cache中的key必定是惟一的，而且只能對應一個value。

(8). 經過cache.get(key)獲取value，這個方法只有一個參數key，而且返回這個key關聯的value,若是這個key沒有關聯的value那麼就返回null.

(9). 咱們可使用CacheManager.removeCache(String)刪除一個給定的cache，CacheManager不只會刪除對Cache的引用，並且還會關閉該Cache，那麼Cache會釋放本地佔用的臨時資源如(memory)。Cache的引用也將不可用了。

(10). 爲了釋放全部的臨時資源(memory，threads)，CacheManager給Cache實例提供了管理方法，你必須調用CacheManager.close()方法，他會依次的關閉全部存在的Cache實例。

 

下面給出針對上面代碼的一個簡短版本，主要涉及三個重要的事情

try(CacheManager cacheManager = newCacheManagerBuilder() (1) .withCache("preConfigured", newCacheConfigurationBuilder(Long.class, String.class, heap(10))) (2) .build(true)) { (3) // Same code as before [...]
}

 

(1). A CacheManager implements Closeable so can be closed automatically by a try-with-resources. A CacheManager must be closed cleanly. In a finally block, with a try-with-resources or (more frequent for normal applications) in some shutdown hook.

(2). Builders having different names, you can use static imports for all of them.

(3). CacheManager經過build(true)進行了初始化。

 

二. 經過XML進行配置

 

<config xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns='http://www.ehcache.org/v3' xsi:schemaLocation="http://www.ehcache.org/v3 http://www.ehcache.org/schema/ehcache-core.xsd">

  <cache alias="foo"> (1)
    <key-type>java.lang.String</key-type>(2) 
    <value-type>java.lang.String</value-type>(2) 
    <resources>
      <heap unit="entries">20</heap> (3)
      <offheap unit="MB">10</offheap> (4)
    </resources>
  </cache>

  <cache-template name="myDefaults"> (5)
    <key-type>java.lang.Long</key-type>
    <value-type>java.lang.String</value-type>
    <heap unit="entries">200</heap>
  </cache-template>

  <cache alias="bar" uses-template="myDefaults"> (6)
    <key-type>java.lang.Number</key-type>
  </cache>

  <cache alias="simpleCache" uses-template="myDefaults" />(7) 

</config>

(1). 定義cache的名字爲foo

(2). foo的key和value類型被定義爲String，若是沒有指定類型，那麼默認爲java.lang.Object。

(3). foo在堆中能夠存儲20個entries

(4). 10M的堆外空間

(5). <cache-template>元素可讓你定義一個配置模板，而後被繼承。

(6). bar就是繼承名字爲"myDefaults"的<cache-template>的一個cache，而且重寫了模板中key-type。

(7). simpleCache是另外一個繼承myDefault的Cache，它徹底使用myDefaults中的配置做爲本身的配置。

 

三. 解析XML配置

 爲了解析XML配置，你可使用XmlConfiguration類型：

URL myUrl = getClass().getResource("/my-config.xml"); (1)
Configuration xmlConfig = new XmlConfiguration(myUrl); (2)
CacheManager myCacheManager = CacheManagerBuilder.newCacheManager(xmlConfig); (3)

(1). 獲取XML文件的url地址。

(2). 經過傳入XML文件的url地址，去實例化一個XmlConfiguration。

(3). 使用靜態方法CacheManagerBuilder.newCacheManager(xmlConfig)去建立CacheManager實例。

 

 四.建立集羣模式的CacheManager

 爲了使用Terracotta(收購了Ehcache和Quartz)的集羣模式，首先你要以集羣存儲模式啓動Terracotta服務，除此以外爲了建立集羣模式的CacheManager，你須要提供集羣配置以下：

CacheManagerBuilder<PersistentCacheManager> clusteredCacheManagerBuilder = CacheManagerBuilder.newCacheManagerBuilder() (1) .with(ClusteringServiceConfigurationBuilder.cluster(URI.create("terracotta://localhost/my-application")) (2) .autoCreate()); (3) PersistentCacheManager cacheManager = clusteredCacheManagerBuilder.build(true); (4) cacheManager.close(); (5)

(1). 返回一個CacheManagerBuilder實例

(2). 使用靜態方法.cluster(URL)，鏈接了CacheManager和ClusteringStorage，而且該方法返回了集羣服務配置的實例，在上面這個例子中提供了一個簡單的URI，用來指定在Terracotta服務上的集羣存儲標識my-application(假設Terracotta這個服務已經在本地的9410端口運行)，參數auto-create表示若是若是不存在那麼就建立這個集羣存儲。

(3). Returns a fully initialized cache manager that can be used to create clustered caches.

(4). Auto-create the clustered storage if it doesn't already exist.

(5). 關閉CacheManager。

 

五. 分層存儲

Ehcache 3和以前的版本同樣，支持分層模型，容許在較慢的層中存儲更多的數據(一般狀況下較慢的層存儲空間更大)。

這個分層的理念是，支持快速存儲的資源很稀缺，因此HotData優先放到該區域。那些訪問頻率不多的數據被移到慢存儲層上。

三層存儲結構，堆空間，堆外空間，磁盤空間。

一個使用三層存儲的典型例子以下

PersistentCacheManager persistentCacheManager = CacheManagerBuilder.newCacheManagerBuilder()
    .with(CacheManagerBuilder.persistence(new File(getStoragePath(), "myData"))) (1)
    .withCache("threeTieredCache",
        CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class,
            ResourcePoolsBuilder.newResourcePoolsBuilder()
                .heap(10, EntryUnit.ENTRIES) (2)
                .offheap(1, MemoryUnit.MB) (3)
                .disk(20, MemoryUnit.MB, true)(4) 
            )
    ).build(true);

Cache<Long, String> threeTieredCache = persistentCacheManager.getCache("threeTieredCache", Long.class, String.class);
threeTieredCache.put(1L, "stillAvailableAfterRestart"); (5)

persistentCacheManager.close();

(1). 若是你想使用磁盤存儲(像持久化Cache那樣)，你須要提供一個數據存儲的路徑給.persistence()靜態方法。

(2). 定義一個heap，這塊空間是最快速存儲的可是空間小。

(3). 定義一個off-heap，這塊空間也是快速的可是空間比上面的大。

(4). 定義一個磁盤持久化存儲。

(5). 當JVM重啓時(假如CacheManager已經關閉了)，cache中的數據也是能夠得到的。

 

 六. 數據新鮮度

 在Ehcache中，數據的新鮮度由Expiry來控制，下面舉例說明如何配置一個time-to-live expirly。

CacheConfiguration<Long, String> cacheConfiguration = CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(100)) (1) .withExpiry(ExpiryPolicyBuilder.timeToLiveExpiration(Duration.ofSeconds(20))) (2) .build();

 

(1). Expiry是在cache級別配置的，因此先定義一個cache配置。

(2). 而後添加一個Expiry，這裏使用的是預約義的time-to-live，他須要一個Duration參數。