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参数。