Ehcache 3.0 Documentation

Ehcache 3.0 Documentation

Configuring Ehcache

In order to start using Ehcache, you will need to configure your first CacheManager and Cache. This can be achieved through programmatic configuration or XML.

在项目中如果你准备使用Ehcache，你需要配置一个CacheManager和Cache这两个对象。这两个对象可以通过项目中的配置对象或者XML获得。

Configuring with Java（通过JAVA配置）

Java configuration is most easily achieved through the use of builders that offer a fluent API.

java配置非常简单，Ehcache提供了很简单的API给你使用

Managed cache（管理缓存）

As with the previous versions of Ehcache, the canonical way of dealing with Cache is through a CacheManager:

就和以前Ehcache的版本一样，通过CacheManager获得Cache是一种典型的方式，看下面的代码：

public class EhcacheTest {
    public static void main(String[] args){
        /**
         * 仔细体会下面两种创建Cache对象的方式
         */
        Cache cache1 = EhcacheTest.wayOne();
        cache1.put("1","a");
        Cache cache2 = EhcacheTest.wayTwo();
        cache2.put("1","a");
    }

    public static Cache wayOne(){
        CacheManager cacheManager = CacheManagerBuilder
                .newCacheManagerBuilder()
                .withCache("wayOne",
                        CacheConfigurationBuilder.newCacheConfigurationBuilder(String.class,String.class,ResourcePoolsBuilder.heap(10))
                ).build();
        cacheManager.init();
        //上面已经创建好了cache的别名：wayOne，所以可以直接调用getCache的到Cache对象
        Cache cache = cacheManager.getCache("wayOne",String.class,String.class);
        return cache;
    }

    public static Cache wayTwo(){
        //直接创建好了CacheManager对象。buile(true)表示构建好直接初始化，可以不用调用init方法
        CacheManager cacheManager = CacheManagerBuilder.newCacheManagerBuilder().build(true);
        //从CacheManager对象上面创建新的Cache对象。调用createCache()方法
        Cache cache = cacheManager.createCache("wayTwo",CacheConfigurationBuilder.newCacheConfigurationBuilder(String.class,String.class,ResourcePoolsBuilder.heap(10)));
        return cache;
    }
}

Storage Tiers

Ehcache 3, as in previous versions, offers a tiering model to allow storing increasing amounts of data on slower tiers (which are generally more abundant).

Ehcache提供了一种层的概念。允许用户存储越来越多的数据到（slower tiers）『缓慢层』中（通常缓慢层都会比较丰富）

The idea is that resources related to faster storage are more rare, but are where the ‘hottest’ data is preferred to be. Thus less-hot (less frequently used) data is moved to the more abundant but slower tiers. Hotter data is faulted onto the faster tiers.

这种存储方式是和数据有关，比较hot的数据会被存放在稀少的快速层中，另外一些不那么hot的数据会被移到丰富但是缓慢的数据层中

off-heap

    public static CacheManager OffHeapDemo(){
        CacheManager cacheManager = CacheManagerBuilder.newCacheManagerBuilder().withCache("tieredCache",
                CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class,
                        ResourcePoolsBuilder.newResourcePoolsBuilder()
                                //.heap(10, EntryUnit.ENTRIES)  //和之前的创建CacheManager一样
                                .offheap(10, MemoryUnit.MB))  //增加offHeap
        ).build(true);
        return cacheManager;
    }

The example above allocates a very small amount of off-heap. Remember that data stored off-heap will have to be serialized and deserialized - and is thus slower than heap. You should thus favor off-heap for large amounts of data where on-heap would have too severe an impact on garbage collection.

上面的例子创建了一个很小的off-heap（对外内存）。记住数据存储到off-heap里面需要序列化和反序列化所以获取的速度比从heap里面要慢。当有大数据时放到off-heap中，堆内对GC影响比较大。

off-heap：将你的对象从堆中脱离出来序列化，然后存储在一大块内存中，这就像它存储到磁盘上一样，但它仍然在RAM中。对象在这种状态下不能直接使用，它们必须首先反序列化，也不受垃圾收集。序列化和反序列化将会影响部分性能（所以可以考虑使用FST-serialization）使用堆外内存能够降低GC导致的暂停。

Disk persistence

PersistentCacheManager persistentCacheManager = CacheManagerBuilder.newCacheManagerBuilder()
    .with(CacheManagerBuilder.persistence(getStoragePath() + File.separator + "myData")) 
    .withCache("persistent-cache", CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class,
        ResourcePoolsBuilder.newResourcePoolsBuilder()
            .heap(10, EntryUnit.ENTRIES)
            .disk(10, MemoryUnit.MB, true)) //持久到磁盘中
        )
    .build(true);

If you wish to use disk storage (like for persistent Cache instances), you’ll have to provide a location where data should be stored on disk to the CacheManagerBuilder.persistence(String) static method.

如果你想使用磁盘存储，你需要提供一个本地的磁盘空间来存储它。可以使用CacheManagerBuilder.persistence这个静态方法设置一个路径。

The example above allocates a very small amount of disk storage. Remember that data stored on disk will have to be serialized / deserialized and written / read from disk - and is thus slower than heap and offheap. You should thus favor disk for large amounts of data.

上面那个例子创建了一个小的磁盘空间存储数据，记住存储或者使用这些数据需要序列化和反序列化或者IO流写/读。它的速度比off-heap慢。因此，您应该对磁盘进行大量的数据处理。

Three tiers

PersistentCacheManager persistentCacheManager = CacheManagerBuilder.newCacheManagerBuilder()
    .with(CacheManagerBuilder.persistence(getStoragePath() + File.separator + "myData")) 
    .withCache("threeTieredCache",
        CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class,
            ResourcePoolsBuilder.newResourcePoolsBuilder()
                .heap(10, EntryUnit.ENTRIES) 
                .offheap(1, MemoryUnit.MB) 
                .disk(20, MemoryUnit.MB) 
            )
    ).build(true);

三种方式组合使用堆内空间heap，堆外内存offheap，磁盘空间disk