ehcache常用API整理

鉴于csdn的blog的不稳定, 及混乱的编辑器, 和无上传功能, 遂决定彻底投诚javaeye的blog.

数月前整理的一个东西, 作为cache的扫盲文档.参考了它的官方文档.

对ehcache感兴趣的兄台可以参考.

附件为eclipse项目, 直接导入, 运行test目录下的junit testcase, 可一目了然.
一 ehcache API:

1: Using the CacheManager

1.1所有ehcache的使用, 都是从 CacheManager. 开始的.
有多种方法创建CacheManager实例:

Java代码

1. //Create a singleton CacheManager using defaults, then list caches.   
2. CacheManager.getInstance()  

//Create a singleton CacheManager using defaults, then list caches.
CacheManager.getInstance()

 

或者:

Java代码

1. //Create a CacheManager instance using defaults, then list caches.   
2. CacheManager manager = new CacheManager();   
3. String[] cacheNames = manager.getCacheNames();  

//Create a CacheManager instance using defaults, then list caches.
CacheManager manager = new CacheManager();
String[] cacheNames = manager.getCacheNames();

 

如果需要从指定配置文件创建 CacheManager:

Java代码

1. Create two CacheManagers, each with a different configuration, and list the caches in each.   
2. CacheManager manager1 = new CacheManager("src/config/ehcache1.xml");   
3. CacheManager manager2 = new CacheManager("src/config/ehcache2.xml");   
4. String[] cacheNamesForManager1 = manager1.getCacheNames();   
5. String[] cacheNamesForManager2 = manager2.getCacheNames();  

Create two CacheManagers, each with a different configuration, and list the caches in each.
CacheManager manager1 = new CacheManager("src/config/ehcache1.xml");
CacheManager manager2 = new CacheManager("src/config/ehcache2.xml");
String[] cacheNamesForManager1 = manager1.getCacheNames();
String[] cacheNamesForManager2 = manager2.getCacheNames();

 

1.2 Adding and Removing Caches Programmatically
手动创建一个cache, 而不是通过配置文件:

Java代码

1. //creates a cache called testCache, which   
2. //will be configured using defaultCache from the configuration   
3. CacheManager singletonManager = CacheManager.create();   
4. singletonManager.addCache("testCache");   
5. Cache test = singletonManager.getCache("testCache");  

//creates a cache called testCache, which
//will be configured using defaultCache from the configuration
CacheManager singletonManager = CacheManager.create();
singletonManager.addCache("testCache");
Cache test = singletonManager.getCache("testCache");

 

或者:

Java代码

1. //Create a Cache and add it to the CacheManager, then use it. Note that Caches are not usable until they have   
2. //been added to a CacheManager.   
3.     public void testCreatCacheByProgram()   
4.     {   
5.         CacheManager singletonManager = CacheManager.create();   
6.         Cache memoryOnlyCache = new Cache("testCache", 5000, false, false, 5, 2);   
7.         singletonManager.addCache(memoryOnlyCache);   
8.         Cache testCache = singletonManager.getCache("testCache");   
9.         assertNotNull(testCache);          
10.     }  

//Create a Cache and add it to the CacheManager, then use it. Note that Caches are not usable until they have
//been added to a CacheManager.
    public void testCreatCacheByProgram()
    {
        CacheManager singletonManager = CacheManager.create();
        Cache memoryOnlyCache = new Cache("testCache", 5000, false, false, 5, 2);
        singletonManager.addCache(memoryOnlyCache);
        Cache testCache = singletonManager.getCache("testCache");
        assertNotNull(testCache);       
    }

 

   
手动移除一个cache:

Java代码

1. //Remove cache called sampleCache1   
2. CacheManager singletonManager = CacheManager.create();   
3. singletonManager.removeCache("sampleCache1");  

//Remove cache called sampleCache1
CacheManager singletonManager = CacheManager.create();
singletonManager.removeCache("sampleCache1");

 

1.3 Shutdown the CacheManager
ehcache应该在使用后关闭, 最佳实践是在code中显式调用:

Java代码

1. //Shutdown the singleton CacheManager   
2. CacheManager.getInstance().shutdown();  

//Shutdown the singleton CacheManager
CacheManager.getInstance().shutdown();

 2 Using Caches
比如我有这样一个cache:

Xml代码

1. <cache name="sampleCache1" maxElementsInMemory="10000"  
2.     maxElementsOnDisk="1000" eternal="false" overflowToDisk="true"  
3.     diskSpoolBufferSizeMB="20" timeToIdleSeconds="300"  
4.     timeToLiveSeconds="600" memoryStoreEvictionPolicy="LFU" />  

    <cache name="sampleCache1" maxElementsInMemory="10000"
        maxElementsOnDisk="1000" eternal="false" overflowToDisk="true"
        diskSpoolBufferSizeMB="20" timeToIdleSeconds="300"
        timeToLiveSeconds="600" memoryStoreEvictionPolicy="LFU" />

 

       
2.1 Obtaining a reference to a Cache
获得该cache的引用:

Java代码

1. String cacheName = "sampleCache1";   
2. CacheManager manager = new CacheManager("src/ehcache1.xml");   
3. Cache cache = manager.getCache(cacheName);  

        String cacheName = "sampleCache1";
        CacheManager manager = new CacheManager("src/ehcache1.xml");
        Cache cache = manager.getCache(cacheName);

 
2.2 Performing CRUD operations
下面的代码演示了ehcache的增删改查:

Java代码

1. public void testCRUD()   
2. {   
3.     String cacheName = "sampleCache1";   
4.     CacheManager manager = new CacheManager("src/ehcache1.xml");   
5.     Cache cache = manager.getCache(cacheName);   
6.     //Put an element into a cache   
7.     Element element = new Element("key1", "value1");   
8.     cache.put(element);   
9.     //This updates the entry for "key1"   
10.     cache.put(new Element("key1", "value2"));   
11.     //Get a Serializable value from an element in a cache with a key of "key1".   
12.     element = cache.get("key1");   
13.     Serializable value = element.getValue();   
14.     //Get a NonSerializable value from an element in a cache with a key of "key1".   
15.     element = cache.get("key1");   
16.     assertNotNull(element);   
17.     Object valueObj = element.getObjectValue();   
18.     assertNotNull(valueObj);   
19.     //Remove an element from a cache with a key of "key1".   
20.     assertNotNull(cache.get("key1"));   
21.     cache.remove("key1");   
22.     assertNull(cache.get("key1"));   
23.       
24. }  

    public void testCRUD()
    {
        String cacheName = "sampleCache1";
        CacheManager manager = new CacheManager("src/ehcache1.xml");
        Cache cache = manager.getCache(cacheName);
        //Put an element into a cache
        Element element = new Element("key1", "value1");
        cache.put(element);
        //This updates the entry for "key1"
        cache.put(new Element("key1", "value2"));
        //Get a Serializable value from an element in a cache with a key of "key1".
        element = cache.get("key1");
        Serializable value = element.getValue();
        //Get a NonSerializable value from an element in a cache with a key of "key1".
        element = cache.get("key1");
        assertNotNull(element);
        Object valueObj = element.getObjectValue();
        assertNotNull(valueObj);
        //Remove an element from a cache with a key of "key1".
        assertNotNull(cache.get("key1"));
        cache.remove("key1");
        assertNull(cache.get("key1"));
       
    }

    
2.3    Disk Persistence on demand

Java代码

1. //sampleCache1 has a persistent diskStore. We wish to ensure that the data //and index are written immediately.   
2.         public void testDiskPersistence()   
3.     {   
4.         String cacheName = "sampleCache1";   
5.         CacheManager manager = new CacheManager("src/ehcache1.xml");   
6.         Cache cache = manager.getCache(cacheName);   
7.         for (int i = 0; i < 50000; i++)   
8.         {   
9.             Element element = new Element("key" + i, "myvalue" + i);   
10.             cache.put(element);   
11.         }   
12.         cache.flush();   
13.         Log.debug("java.io.tmpdir = " + System.getProperty("java.io.tmpdir"));   
14.     }  

//sampleCache1 has a persistent diskStore. We wish to ensure that the data //and index are written immediately.
        public void testDiskPersistence()
    {
        String cacheName = "sampleCache1";
        CacheManager manager = new CacheManager("src/ehcache1.xml");
        Cache cache = manager.getCache(cacheName);
        for (int i = 0; i < 50000; i++)
        {
            Element element = new Element("key" + i, "myvalue" + i);
            cache.put(element);
        }
        cache.flush();
        Log.debug("java.io.tmpdir = " + System.getProperty("java.io.tmpdir"));
    }

 

备注: 持久化到硬盘的路径由虚拟机参数"java.io.tmpdir"决定.
例如, 在windows中, 会在此路径下
C:/Documents and Settings/li/Local Settings/Temp
在linux中, 通常会在: /tmp 下

2.4  Obtaining Cache Sizes
以下代码演示如何获得cache个数:

Java代码

1. public void testCachesizes()   
2. {   
3.     long count = 5;   
4.     String cacheName = "sampleCache1";   
5.     CacheManager manager = new CacheManager("src/ehcache1.xml");   
6.     Cache cache = manager.getCache(cacheName);   
7.     for (int i = 0; i < count; i++)   
8.     {   
9.         Element element = new Element("key" + i, "myvalue" + i);   
10.         cache.put(element);   
11.     }   
12.     //Get the number of elements currently in the Cache.   
13.     int elementsInCache = cache.getSize();   
14.     assertTrue(elementsInCache == 5);   
15.     //Cache cache = manager.getCache("sampleCache1");   
16.     long elementsInMemory = cache.getMemoryStoreSize();   
17.     //Get the number of elements currently in the DiskStore.   
18.     long elementsInDiskStore = cache.getDiskStoreSize();   
19.     assertTrue(elementsInMemory + elementsInDiskStore == count);      
20. }   

    public void testCachesizes()
    {
        long count = 5;
        String cacheName = "sampleCache1";
        CacheManager manager = new CacheManager("src/ehcache1.xml");
        Cache cache = manager.getCache(cacheName);
        for (int i = 0; i < count; i++)
        {
            Element element = new Element("key" + i, "myvalue" + i);
            cache.put(element);
        }
        //Get the number of elements currently in the Cache.
        int elementsInCache = cache.getSize();
        assertTrue(elementsInCache == 5);
        //Cache cache = manager.getCache("sampleCache1");
        long elementsInMemory = cache.getMemoryStoreSize();
        //Get the number of elements currently in the DiskStore.
        long elementsInDiskStore = cache.getDiskStoreSize();
        assertTrue(elementsInMemory + elementsInDiskStore == count);   
    }
    

 

3: Registering CacheStatistics in an MBeanServer
ehCache 提供jmx支持:

Java代码

1. CacheManager manager = new CacheManager();   
2. MBeanServer mBeanServer = ManagementFactory.getPlatformMBeanServer();   
3. ManagementService.registerMBeans(manager, mBeanServer, false, false, false, true);  

CacheManager manager = new CacheManager();
MBeanServer mBeanServer = ManagementFactory.getPlatformMBeanServer();
ManagementService.registerMBeans(manager, mBeanServer, false, false, false, true);

 

把该程序打包, 然后:

Java代码

1. java -Dcom.sun.management.jmxremote -jar 程序名.jar  

java -Dcom.sun.management.jmxremote -jar 程序名.jar

 
再到javahome/bin中运行jconsole.exe, 便可监控cache.

4. 用户可以自定义处理cacheEventHandler, 处理诸如元素放入cache的各种事件(放入,移除,过期等事件)
只需三步:
4.1 在cache配置中, 增加cacheEventListenerFactory节点.

Java代码

1. <cache name="Test" maxElementsInMemory="1" eternal="false"  
2.     overflowToDisk="true" timeToIdleSeconds="1" timeToLiveSeconds="2"  
3.     diskPersistent="false" diskExpiryThreadIntervalSeconds="1"  
4.     memoryStoreEvictionPolicy="LFU">   
5.     <cacheEventListenerFactory class="co.ehcache.EventFactory" />   
6. </cache>  

    <cache name="Test" maxElementsInMemory="1" eternal="false"
        overflowToDisk="true" timeToIdleSeconds="1" timeToLiveSeconds="2"
        diskPersistent="false" diskExpiryThreadIntervalSeconds="1"
        memoryStoreEvictionPolicy="LFU">
        <cacheEventListenerFactory class="co.ehcache.EventFactory" />
    </cache>

 

4.2: 编写EventFactory, 继承CacheEventListenerFactory:

Java代码

1. public class EventFactory extends CacheEventListenerFactory    
2. {   
3.     @Override  
4.     public CacheEventListener createCacheEventListener(Properties properties)   
5.     {   
6.         // TODO Auto-generated method stub   
7.         return new CacheEvent();   
8.     }   
9.   
10. }  

public class EventFactory extends CacheEventListenerFactory 
{
    @Override
    public CacheEventListener createCacheEventListener(Properties properties)
    {
        // TODO Auto-generated method stub
        return new CacheEvent();
    }

}

 

4.3  编写 class: CacheEvent, 实现 CacheEventListener 接口:

Java代码

1. public class CacheEvent implements CacheEventListener    
2. {   
3.   
4.     public void dispose()   
5.     {   
6.         log("in dispose");   
7.     }   
8.   
9.     public void notifyElementEvicted(Ehcache cache, Element element)   
10.     {   
11.         // TODO Auto-generated method stub   
12.         log("in notifyElementEvicted" + element);   
13.     }   
14.   
15.     public void notifyElementExpired(Ehcache cache, Element element)   
16.     {   
17.         // TODO Auto-generated method stub   
18.         log("in notifyElementExpired" + element);   
19.     }   
20.   
21.     public void notifyElementPut(Ehcache cache, Element element) throws CacheException   
22.     {   
23.         // TODO Auto-generated method stub   
24.         log("in notifyElementPut" + element);   
25.     }   
26.   
27.     public void notifyElementRemoved(Ehcache cache, Element element) throws CacheException   
28.     {   
29.         // TODO Auto-generated method stub   
30.         log("in notifyElementRemoved" + element);   
31.     }   
32.   
33.     public void notifyElementUpdated(Ehcache cache, Element element) throws CacheException   
34.     {   
35.         // TODO Auto-generated method stub   
36.         log("in notifyElementUpdated" + element);   
37.     }   
38.   
39.     public void notifyRemoveAll(Ehcache cache)   
40.     {   
41.         // TODO Auto-generated method stub   
42.         log("in notifyRemoveAll");   
43.     }   
44.       
45.     public Object clone() throws CloneNotSupportedException   
46.     {   
47.         return super.clone();   
48.     }      
49.       
50.     private void log(String s)   
51.     {   
52.         Log.debug(s);   
53.     }   
54. }  

public class CacheEvent implements CacheEventListener 
{

    public void dispose()
    {
        log("in dispose");
    }

    public void notifyElementEvicted(Ehcache cache, Element element)
    {
        // TODO Auto-generated method stub
        log("in notifyElementEvicted" + element);
    }

    public void notifyElementExpired(Ehcache cache, Element element)
    {
        // TODO Auto-generated method stub
        log("in notifyElementExpired" + element);
    }

    public void notifyElementPut(Ehcache cache, Element element) throws CacheException
    {
        // TODO Auto-generated method stub
        log("in notifyElementPut" + element);
    }

    public void notifyElementRemoved(Ehcache cache, Element element) throws CacheException
    {
        // TODO Auto-generated method stub
        log("in notifyElementRemoved" + element);
    }

    public void notifyElementUpdated(Ehcache cache, Element element) throws CacheException
    {
        // TODO Auto-generated method stub
        log("in notifyElementUpdated" + element);
    }

    public void notifyRemoveAll(Ehcache cache)
    {
        // TODO Auto-generated method stub
        log("in notifyRemoveAll");
    }
   
    public Object clone() throws CloneNotSupportedException
    {
        return super.clone();
    }   
   
    private void log(String s)
    {
        Log.debug(s);
    }
}

 

现在可以编写测试代码:

Java代码

1. public void testEventListener()   
2. {   
3.     String key = "person";   
4.     Person person = new Person("lcl", 100);   
5.     MyCacheManager.getInstance().put("Test", key, person);   
6.     Person p = (Person) MyCacheManager.getInstance().get("Test", key);   
7.   
8.     try  
9.     {   
10.         Thread.sleep(10000);   
11.     }   
12.     catch (InterruptedException e)   
13.     {   
14.         // TODO Auto-generated catch block   
15.         e.printStackTrace();   
16.     }   
17.   
18.     assertNull(MyCacheManager.getInstance().get("Test", key));   
19. }  

    public void testEventListener()
    {
        String key = "person";
        Person person = new Person("lcl", 100);
        MyCacheManager.getInstance().put("Test", key, person);
        Person p = (Person) MyCacheManager.getInstance().get("Test", key);

        try
        {
            Thread.sleep(10000);
        }
        catch (InterruptedException e)
        {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }

        assertNull(MyCacheManager.getInstance().get("Test", key));
    }

 

   
    根据配置, 该缓存对象生命期只有2分钟, 在Thread.sleep(10000)期间, 该缓存元素将过期被销毁, 在销毁前, 触发notifyElementExpired事件.
   
二 Ehcache配置文件
 以如下配置为例说明:

Xml代码

1. <cache name="CACHE_FUNC"    
2. maxElementsInMemory="2"    
3. eternal="false"    
4. timeToIdleSeconds="10"    
5. timeToLiveSeconds="20"  
6. overflowToDisk="true"    
7. diskPersistent="true"    
8. diskExpiryThreadIntervalSeconds="120"  />  

<cache name="CACHE_FUNC" 
maxElementsInMemory="2" 
eternal="false" 
timeToIdleSeconds="10" 
timeToLiveSeconds="20"
overflowToDisk="true" 
diskPersistent="true" 
diskExpiryThreadIntervalSeconds="120"  />

 

maxElementsInMemory ：cache 中最多可以存放的元素的数量。如果放入cache中的元素超过这个数值，有两种情况：
1. 若overflowToDisk的属性值为true，会将cache中多出的元素放入磁盘文件中。
2. 若overflowToDisk的属性值为false，会根据memoryStoreEvictionPolicy的策略替换cache中原有的元素。

eternal ：是否永驻内存。如果值是true，cache中的元素将一直保存在内存中，不会因为时间超时而丢失，所以在这个值为true的时候，timeToIdleSeconds和timeToLiveSeconds两个属性的值就不起作用了。

 3. timeToIdleSeconds ：访问这个cache中元素的最大间隔时间。如果超过这个时间没有访问这个cache中的某个元素，那么这个元素将被从cache中清除。

4. timeToLiveSeconds : cache中元素的生存时间。意思是从cache中的某个元素从创建到消亡的时间，从创建开始计时，当超过这个时间，这个元素将被从cache中清除。

5. overflowToDisk ：溢出是否写入磁盘。系统会根据标签<diskStore path="java.io.tmpdir"/> 中path的值查找对应的属性值，如果系统的java.io.tmpdir的值是 D:/temp，写入磁盘的文件就会放在这个文件夹下。文件的名称是cache的名称，后缀名的data。如：CACHE_FUNC.data。

6. diskExpiryThreadIntervalSeconds  ：磁盘缓存的清理线程运行间隔.

7. memoryStoreEvictionPolicy ：内存存储与释放策略。有三个值：
LRU －least recently used
LFU －least frequently used
FIFO－first in first out, the oldest element by creation time

diskPersistent ： 是否持久化磁盘缓存。当这个属性的值为true时，系统在初始化的时候会在磁盘中查找文件名为cache名称，后缀名为index的的文件，如CACHE_FUNC.index 。这个文件中存放了已经持久化在磁盘中的cache的index，找到后把cache加载到内存。要想把cache真正持久化到磁盘，写程序时必须注意，在是用net.sf.ehcache.Cache的void put (Element element)方法后要使用void flush()方法。
 更多说明可看ehcache自带的ehcache.xml的注释说明.