Ehcache 3.8 文档(官方文档翻译)

  |   0 评论   |   0 浏览

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 磁盘持久性

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


标题:Ehcache 3.8 文档(官方文档翻译)
作者:MingGH
地址:https://www.runnable.run/articles/2020/09/05/1599316050438.html