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