Ehcache 3.8 文档

一、配置Ehcache

为了开始使用Ehcache，您需要配置第一个CacheManager和Cache。这可以通过编程配置或XML来实现。

如果你想使用JSR-107，也就是javax.cacheAPI，您应该首先阅读Ehcache 3.x JSR-107提供程序页面。

1.1 程序配置

通过使用提供流畅API的构建器，最容易实现Java配置。

与早期版本的Ehcache一样，处理Cache的规范方法是通过CacheManager。

// 这个静态方法org.ehcache.config.builders.CacheManagerBuilder.newCacheManagerBuilder返回一个新的org.ehcache.config.builders.CacheManagerBuilder实例
CacheManager cacheManager = CacheManagerBuilder.newCacheManagerBuilder()
   //使用构建器来定义别名为“ preConfigured”的缓存。
   //在实际的CacheManager实例上调用cacheManager.build（）时，将创建此缓存。
   //第一个字符串参数是缓存别名，用于从CacheManager检索缓存。
   //第二个参数，org.ehcache.config.CacheConfiguration，用于配置缓存。我们使用静态newCacheConfigurationBuilder（）方法org.ehcache.config.builders.CacheConfigurationBuilder创建默认配置。
    .withCache("preConfigured",
        CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(10)))
    //最后，调用build（）返回我们可以使用的完全实例化但未初始化的CacheManager。
    .build();
    //在使用CacheManager之前，需要对其进行初始化，可以使用以下2种方法之一进行初始化：
    //在CacheManager实例上调用CacheManager.init（），或在boolean参数设置为true的情况下调用CacheManagerBuilder.build（boolean init）方法。
cacheManager.init();
//通过将其别名，键类型和值类型传递给CacheManager来检索缓存。
//例如，要获取在步骤2中声明的缓存，您需要使用其别名=“ preConfigured”，keyType = Long.class和valueType = String.class。
//为了确保类型安全，我们要求同时传递键和值类型。
//如果这些与我们期望的有所不同，则CacheManager在应用程序生命周期的早期会引发ClassCastException。
//这可以防止缓存受到随机类型的污染。
Cache<Long, String> preConfigured =
    cacheManager.getCache("preConfigured", Long.class, String.class);
    //可以根据需要使用CacheManager创建新的Cache实例。
    //就像在步骤2中一样，它需要传入别名以及CacheConfiguration。
    //添加的实例化和完全初始化的Cache将通过CacheManager.getCache API返回和/或访问。
Cache<Long, String> myCache = cacheManager.createCache("myCache",
    CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(10)));
//现在可以使用新添加的缓存来存储条目，这些条目由键值对组成。put方法的第一个参数是键，第二个参数是值。
//请记住，键和值类型必须与CacheConfiguration中定义的类型相同。
//此外，key必须唯一，并且仅与一个值相关联。
myCache.put(1L, "da one!");
//通过调用cache.get（key）方法从缓存中检索值。
//它仅采用一个参数作为键，并返回与该键关联的值。
//如果没有与该键关联的值，则返回null。
String value = myCache.get(1L);
//我们可以CacheManager.removeCache（String）给定的缓存。
//CacheManager将不仅删除其对Cache的引用，还将关闭它。
//缓存释放所有本地保留的瞬时资源（例如内存）。
//对此缓存的引用变得不可用。
cacheManager.removeCache("preConfigured");
//为了释放CacheManager提供给它管理的Cache实例的所有瞬时资源（内存，线程等），您必须调用CacheManager.close（），后者依次关闭当时已知的所有Cache实例。
cacheManager.close();

下面是一个简短的版本，其中包括三个重要内容：

//CacheManager实现Closeable，因此可以通过try-with-resources自动关闭。
//必须完全关闭CacheManager。
//在finally块中，使用try-with-resources或（在常规应用程序中更常见）在某些关闭钩子中。
try(CacheManager cacheManager = newCacheManagerBuilder()
	//具有不同名称的构建器，对它们可以使用静态导入。
  .withCache("preConfigured", newCacheConfigurationBuilder(Long.class, String.class, heap(10)))
  //使用build（true）初始化CacheManager。
  .build(true)) {

  // Same code as before [...]
}

1.2 XML 配置

您可以创建XML文件来配置CacheManager。

<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">
 <!-- 声明别名为foo的Cache。 -->
  <cache alias="foo">
  	<!-- foo的键和值声明为String类型； -->
<!-- 如果未指定，则默认值为java.lang.Object。 -->
    <key-type>java.lang.String</key-type>
    <value-type>java.lang.String</value-type>
    <resources>
    	<!-- 声明foo最多可在堆上容纳2,000个条目… -->
      <heap unit="entries">20</heap>
      <!-- …以及开始GC回收之前的高达500 MB的堆外内存 -->
      <offheap unit="MB">10</offheap>
    </resources>
  </cache>
<!-- <cache-template>元素允许您创建一个抽象配置，进一步的<cache>配置可以随后“扩展” -->
  <cache-template name="myDefaults">
    <key-type>java.lang.Long</key-type>
    <value-type>java.lang.String</value-type>
    <heap unit="entries">200</heap>
  </cache-template>
<!-- bar就是这样的缓存。bar使用名为myDefaults的<cache-template>并将其键类型覆盖为更自定义的类型。 -->
  <cache alias="bar" uses-template="myDefaults">
    <key-type>java.lang.Number</key-type>
  </cache>
<!-- simpleCache是​​另一个这样的Cache。它使用myDefaults配置作为其唯一的CacheConfiguration。 -->
  <cache alias="simpleCache" uses-template="myDefaults" />

</config>

有关XML格式的更多详细信息，请参考XML文档

为了解析XML配置，可以使用XmlConfiguration类型：

//获取指向您的XML文件位置的URL
URL myUrl = getClass().getResource("/my-config.xml");
//实例化传递XML文件URL的XmlConfiguration
Configuration xmlConfig = new XmlConfiguration(myUrl);
//通过使用静态org.ehcache.config.builders.CacheManagerBuilder.newCacheManager（org.ehcache.config.Configuration），您可以使用XmlConfiguration中的Configuration创建CacheManager实例
CacheManager myCacheManager = CacheManagerBuilder.newCacheManager(xmlConfig);

1.3 创建具有集群支持的缓存管理器

要启用Terracotta群集，首先，您必须启动配置了群集存储的Terracotta服务器。另外，要创建具有集群支持的缓存管理器，您将需要提供集群服务配置：

//返回org.ehcache.config.builders.CacheManagerBuilder实例；
CacheManagerBuilder<PersistentCacheManager> clusteredCacheManagerBuilder =
    CacheManagerBuilder.newCacheManagerBuilder()
    //使用ClusteringServiceConfigurationBuilder的静态方法.cluster（URI）通过指定的URI将缓存管理器连接到集群存储，该URI返回集群服务配置构建器实例。
    //该示例中提供的样本URI指向Terracotta服务器上的群集存储，其中群集存储标识符为my-application（假设服务器在本地主机和端口9410上运行）；
    //自动创建query-param会在服务器中创建集群存储。
        .with(ClusteringServiceConfigurationBuilder.cluster(URI.create("terracotta://localhost/my-application"))
        	//返回一个完全初始化的缓存管理器，可用于创建集群缓存。
            .autoCreate(c -> c));
        //自动创建群集存储（如果尚不存在）。
PersistentCacheManager cacheManager = clusteredCacheManagerBuilder.build(true);
//关闭缓存管理器。
cacheManager.close();

有关此功能的更多信息，请参见群集缓存文档。

1.4 储存层

与以前的版本一样，Ehcache 3提供了分层模型，可以将越来越多的数据存储在较慢的层（通常更为丰富）上。 这个想法是，与更快的存储相关的资源更为稀少，但它们位于首选“最热”数据的位置。因此，热度较低（较少使用）的数据将移至更丰富但速度较慢的层。较热的数据将移至更快的层。

1.4.1 Three tiers三层

一个经典的示例是将Three tiers与永久磁盘存储一起使用。

//如果您想使用磁盘存储（例如用于持久性Cache实例），则必须向CacheManagerBuilder.persistence（）静态方法提供一个位置，该位置应将数据存储在磁盘上。
PersistentCacheManager persistentCacheManager = CacheManagerBuilder.newCacheManagerBuilder()
    .with(CacheManagerBuilder.persistence(new File(getStoragePath(), "myData")))
    .withCache("threeTieredCache",
        CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class,
            ResourcePoolsBuilder.newResourcePoolsBuilder()
            //您为heap定义资源池。这将是您更快但更小的池。
                .heap(10, EntryUnit.ENTRIES)
                //您可以为offheap定义资源池。仍然相当快，并且更大。
                .offheap(1, MemoryUnit.MB)
                //您为磁盘定义一个持久资源池。之所以持久，是因为它应该是（最后一个参数为true）。
                .disk(20, MemoryUnit.MB, true)
            )
    ).build(true);
Cache<Long, String> threeTieredCache = persistentCacheManager.getCache("threeTieredCache", Long.class, String.class);
//JVM重新启动后，存储在缓存中的所有值将可用（假设通过调用close（）干净地关闭了CacheManager）。
threeTieredCache.put(1L, "stillAvailableAfterRestart");

persistentCacheManager.close();

有关详细信息，请阅读分层文档。

1.4.2 数据新鲜度

在Ehcache中，数据更新是通过Expiry控制的。下面说明了如何配置生存期。

//过期是在缓存级别配置的，因此首先定义缓存配置
CacheConfiguration<Long, String> cacheConfiguration = CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class,
        ResourcePoolsBuilder.heap(100))
//然后向其添加一个到期时间，此处使用预定义的生存时间，并配置所需的持续时间。
    .withExpiry(ExpiryPolicyBuilder.timeToLiveExpiration(Duration.ofSeconds(20)))
    .build();

有关可用选项的更多信息，请参见到期部分。

二、进阶主题

此处讨论的许多高级主题已移出，请参见下文。

2.1 用户管理的缓存

有关此功能的更多信息，请参见用户管理的缓存文档

2.2 字节大小的堆

有关此功能的更多信息，请参见分层文档中的相关部分。

2.3 更新资源池

有关此功能的更多信息，请参见分层文档中的相关部分。

2.4 堆外内存

有关此功能的更多信息，请参见分层文档。

2.5 磁盘持久性

有关此功能的更多信息，请参见分层文档。