Ehcache 3.7文檔—基礎篇—XML Configuration
你可以使用xml配置創建CacheManager，根據這個schema definition ( http://www.ehcache.org/documentation/3.7/xsds.html#core )
一. 配置元素
<config> 根元素
config是我們xml配置文件的根元素。它代表了CacheManager的配置。
註意：Ehcache允許創建多個CacaheManager使用相同的XML配置文件。與JSR-107 javax.cache.spi.CachingProvider相對比，Ehcache不維護已創建的CacheManager的實例。
<service>元素
service元素是CacheManager所管理服務的擴展點。
用這種方式定義的service他的生命周期和管理他的CacheManger生命周期一樣。對於這樣的service，當CacheManager.init被調用時會觸發Service.start方法。當CacheManger.close被調用時會觸發Service.stop方法。
CacaheManger管理的那些Cache可以使用這些Service的實例。
JSR-107使用XML配置的擴展點在[ http://www.ehcache.org/documentation/3.7/107.html#supplement-jsr-107-configurations ]這裏有介紹。
<default-serializers>元素
default-serializers元素代表了CacheManger級別的序列化配置。它是<serializer>元素的集合，<serializer>元素包含了一個type和Serializer類的全限定名。
<default-copiers>元素
default-copiers元素代表了CacheManger級別的Copiers配置，它是<copier>元素的集合，<copier>元素包含了一個type和Copier類的全限定名。
<persistence>元素
persistence元素代表了持久化，當創建PersistentCacheManager時使用它。它包含一個數據存儲到Disk時的目錄。
<cache>元素
一個cache元素代表一個Cache實例，這個實例被CacheManager創建並管理。每個cache元素需要一個alias屬性，根據這個alias屬性去調用org.ehcache.CacheManager.getCache(String,Class<K>,Class<V>)，獲得相應的cache實例。也可以使用uses-template屬性去引用一個<cache-template>。了解詳情參見[ http://www.ehcache.org/documentation/3.7/xml.html#cache-template-elements ]
如下元素是可選的：
- <key-type>: Cache<K,V>中K的全限定類名，默認是java.lang.Object
- <value-type>: Cache<K,V>中V的全限定類名，默認是java.lang.Object
- <expiry>: 控制expiry的類型和他的參數
- <eviction-advisor>: 實現org.ehcache.config.EvictionAdvisor<K,V>類的全限定名，默認是null
- <integration>: 用於配置cache-through模式的CacheLoaderWriter
- <resources>: 配置層的信息和層的容量，當只是用heap層時，你可以使用<heap>元素代替它
<cache-template>元素
cache-template元素是<cache>元素的模板，它具有唯一性，可以通過name屬性設置名字。cache元素通過使用uses-template屬性指定cache-template的名字可以繼承該模板中所有的屬性值。當然<cache>也可以重寫模板中的屬性。
註意：Processing of cache template configurations can be triggered lazily by actions that dynamically bind new caches to existing cache templates. Errors within such templates may not be revealed until this lazy processing is triggered.
二. XML配置文件中屬性替換
在XML配置文件內部可以引用java system properties值，在配置解析時這些引用會被替換為value。
使用的語法格式為${prop.name}，他可以用在所有attributes和elements的值上，目前這個規則不包含用來調整大小的數字和標識符，例如cache和cache-template的名字。
註意：如果這個系統屬性不存在，那麽會導致配置解析失敗。
一個典型的應用是在<persistence>標簽中的directory屬性上，配置file路徑
<persistence directory="${user.home}/cache-data"/>(1)
這裏的user.home將會被系統中的屬性替換，比如說替換成/home/user
三. XML配置解析
如果你能通過JSP-107API獲取CacheManager，當你在調用javax.cache.spi.CachingProvider.getCacheManager(java.net.URI,java.lang.ClassLoader)後，接下來的事情會自動完成。
final URL myUrl = getClass().getResource("/configs/docs/getting-started.xml"); (1) XmlConfiguration xmlConfig = new XmlConfiguration(myUrl); (2) CacheManager myCacheManager = CacheManagerBuilder.newCacheManager(xmlConfig); (3) myCacheManager.init(); (4)
(1). 獲取xml文件的位置
(2). 通過xml文件的url實例化一個XmlConfiguration
(3). 使用靜態方法CacheManagerBuilder.newCacheManager(Configuration)創建CacheManager
(4). 在使用之前要初始化cacheManager
我們也可以使用<cache-template>來作為CacheConfigurationBuilder的配置，為了使用<cache-template>元素你需要創建一個xml文件，包含如下內容：
<cache-template name="example"> <key-type>java.lang.Long</key-type> <value-type>java.lang.String</value-type> <heap unit="entries">200</heap> </cache-template>
用如下的方式創建CacheConfigurationBuilder
XmlConfiguration xmlConfiguration = new XmlConfiguration(getClass().getResource("/configs/docs/template-sample.xml")); CacheConfigurationBuilder<Long, String> configurationBuilder = xmlConfiguration.newCacheConfigurationBuilderFromTemplate("example", Long.class, String.class); (1) configurationBuilder = configurationBuilder.withResourcePools(ResourcePoolsBuilder.heap(1000)); (2)
(1). 創建builder，繼承cache-template的屬性，heap的大小為200個entry。
(2). 重寫繼承的屬性
四. 編程的方式配置XML文件
就像根據xml文件創建cache manager一樣，反向翻譯也是支持的。
CacheManager cacheManager = CacheManagerBuilder.newCacheManagerBuilder() .with(CacheManagerBuilder.persistence(tmpDir.newFile("myData"))) .withCache("threeTieredCache", CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.newResourcePoolsBuilder() .heap(10, EntryUnit.ENTRIES) .offheap(1, MemoryUnit.MB) .disk(20, MemoryUnit.MB, true)) .withExpiry(ExpiryPolicyBuilder.timeToIdleExpiration(Duration.ofSeconds(20))) ).build(false); Configuration configuration = cacheManager.getRuntimeConfiguration(); XmlConfiguration xmlConfiguration = new XmlConfiguration(configuration); (1) String xml = xmlConfiguration.toString(); (2)
(1). 通過CacheManager的configuration來實例化一個XmlConfiguration
(2). 通過使用toString方法來獲得xml內容
不是所有的編程式的配置都可以轉換成xml文件的，如果cache manager中包含了如下的內容就不可以轉換：
- EvictionAdvisor
- 自定義的ExpiryPolicy，而不是從ExpiryPolicyBuilder從獲取的timeToLiveExpiration或者是timeToIdleExpiration
- 使用實例代替他們的classes:
a. Serializer
b. Copier
c. CacheLoaderWriter
d. CacheEventListener
e. ResilienceStrategy
五. 在一個文件中配置多個CacheManager
使用該特性最簡單配置就是嵌套多個cache manager configurations在同一個xml文件中。
<multi:configurations xmlns:xsi=‘http://www.w3.org/2001/XMLSchema-instance‘ xmlns=‘http://www.ehcache.org/v3‘ xmlns:multi=‘http://www.ehcache.org/v3/multi‘ xsi:schemaLocation=‘http://www.ehcache.org/v3 http://www.ehcache.org/schema/ehcache-core.xsd http://www.ehcache.org/v3/multi http://www.ehcache.org/schema/ehcache-multi.xsd‘> <!--1--> <multi:configuration identity="foo-manager"> <!--2--> <config> <cache alias="foo"> <key-type>java.lang.String</key-type> <value-type>java.lang.String</value-type> <resources> <heap unit="entries">20</heap> <offheap unit="MB">10</offheap> </resources> </cache> </config> </multi:configuration> <multi:configuration identity="bar-manager"> <config> <cache alias="bar"> <key-type>java.lang.String</key-type> <value-type>java.lang.String</value-type> <resources> <heap unit="entries">20</heap> <offheap unit="MB">10</offheap> </resources> </cache> </config> </multi:configuration> </multi:configurations>
(1). 最頂級的元素<configurations>包含了namespace和一些核心schema。
(2). 每個Ehcache的配置都包含在configuration標簽中，並且他需要一個唯一的標識identity屬性。
通過xml文檔創建XmlMultiConfiguration實例。
XmlMultiConfiguration multipleConfiguration = XmlMultiConfiguration .from(getClass().getResource("/configs/docs/multi/multiple-managers.xml")) (1) .build(); (2) Configuration fooConfiguration = multipleConfiguration.configuration("foo-manager"); (3)
(1). XmlMultiConfiguration是XML文件中resource的集合
(2). 構建這個配置
(3). 可以通過他們的identites獲取Configuration實例
多個CacheManager的變體
對於給定的manager，可以通過包含一系列<variant>標簽來提供變體配置，每個標簽中都需要一個type屬性。
<multi:configurations xmlns:xsi=‘http://www.w3.org/2001/XMLSchema-instance‘ xmlns=‘http://www.ehcache.org/v3‘ xmlns:multi=‘http://www.ehcache.org/v3/multi‘ xsi:schemaLocation=‘http://www.ehcache.org/v3 http://www.ehcache.org/schema/ehcache-core.xsd http://www.ehcache.org/v3/multi http://www.ehcache.org/schema/ehcache-multi.xsd‘> <!-- tag::variants[] --> <multi:configuration identity="foo-manager"> <multi:variant type="heap"> <config> <cache alias="foo"> <key-type>java.lang.String</key-type> <value-type>java.lang.String</value-type> <resources> <heap unit="entries">1000</heap> </resources> </cache> </config> </multi:variant> <multi:variant type="offheap"> <config> <cache alias="foo"> <key-type>java.lang.String</key-type> <value-type>java.lang.String</value-type> <resources> <heap unit="entries">1000</heap> <offheap unit="MB">128</offheap> </resources> </cache> </config> </multi:variant> </multi:configuration> <!-- end::variants[] --> <multi:configuration identity="bar-manager"> <config> <cache alias="bar"> <key-type>java.lang.String</key-type> <value-type>java.lang.String</value-type> <resources> <heap unit="entries">1000</heap> </resources> </cache> </config> </multi:configuration> </multi:configurations>
可以通過指定variant和identity來獲取一個cache configuration
Configuration fooConfiguration = variantConfiguration.configuration("foo-manager", "offheap");
上面的僅僅是一個例子，variant的類型可以有很多種：development vs production，clustered vs unclustered，red vs blue等等。
註意：當Configurations中有多個variant時必須有一個variant指定type，否則在獲取時會拋出IllegalStateException異常。當Configurations中沒有多個variants時將始終為所有的請求返回單個的配置。
獲取多個CacheManager
通過遍歷identites，可以從XmlMultiConfiguration中獲取多個CacheManager
Map<String, Configuration> allConfigurations = multipleConfiguration.identities().stream() // <1> .collect(Collectors.toMap(i -> i, i -> multipleConfiguration.configuration(i))); // <2> Map<String, Configuration> offheapConfigurations = variantConfiguration.identities().stream() .collect(Collectors.toMap(i -> i, i -> variantConfiguration.configuration(i, "offheap"))); // <3>
(1). 多個配置中identites集合的stream
(2). 映射每個identity到他的唯一配置上
(3). 另一種選擇為映射每個identity到指定的variant配置上
構建多個配置的XML
XmlMultiConfiguration實例可以被組裝和修改通過使用相關的API，之前解析XML Multi-Configuration的例子僅僅是一個簡單的調用。
Configurations可以從頭被構建，像下面那樣：
XmlMultiConfiguration multiConfiguration = XmlMultiConfiguration.fromNothing() // <1> .withManager("bar", barConfiguration) // <2> .withManager("foo").variant("heap", heapConfiguration).variant("offheap", offheapConfiguration) // <3> .build(); // <4>
(1). 創建一個空的XmlMultiConfiguration
(2). 添加configuration，不帶variants
(3). 添加一個configuration帶兩個不同的variants：heap和offheap
(4). 構建最終的configuration實例
他們也可以通過已經存在的配置中構建
XmlMultiConfiguration modified = XmlMultiConfiguration.from(multiConfiguration) // <1> .withManager("foo") // <2> .build();
(1). multiConfiguration是一個已經存在配置
(2). Remove the configuration with identity "foo"
以xml的格式獲取一個已經構建的multi-configuration
String xmlString = multiConfiguration.asRenderedDocument(); // <1> Document xmlDocument = multiConfiguration.asDocument(); // <2>
(1). 以字符串的形式獲取xml
(2). 以DOM的形式獲取xml
Ehcache 3.7文檔—基礎篇—XML Configuration