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