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中包含了以下的內容就不能夠轉換：

1. EvictionAdvisor
2. 自定義的ExpiryPolicy，而不是從ExpiryPolicyBuilder從獲取的timeToLiveExpiration或者是timeToIdleExpiration
3. 使用實例代替他們的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