Ehcache(2.9.x) - API Developer Guide, Basic Caching

Creating a CacheManager

All usages of the Ehcache API start with the creation of a CacheManager. The following code snippets illustrate various ways to create one.

Singleton versus Instance

The following creates a singleton CacheManager using defaults, then list caches.

CacheManager.create();
String[] cacheNames = CacheManager.getInstance().getCacheNames();

The following creates a CacheManager instance using defaults, then list caches.

CacheManager manager = CacheManager.newInstance();
String[] cacheNames = manager.getCacheNames();

The following creates two CacheManagers, each with a different configuration, and list the caches in each.

CacheManager manager1 = CacheManager.newInstance("src/config/ehcache1.xml");
CacheManager manager2 = CacheManager.newInstance("src/config/ehcache2.xml");
String[] cacheNamesForManager1 = manager1.getCacheNames();
String[] cacheNamesForManager2 = manager2.getCacheNames();

Loading a Configuration

When a CacheManager is created, it creates caches found in a provided configuration.

The following creates a CacheManager based on the configuration defined in the ehcache.xml file in the classpath.

CacheManager manager = CacheManager.newInstance();

The following creates a CacheManager based on a specified configuration file.

CacheManager manager = CacheManager.newInstance("src/config/ehcache.xml");

The following creates a CacheManager from a configuration resource in the classpath.

URL url = getClass().getResource("/anotherconfigurationname.xml");
CacheManager manager = CacheManager.newInstance(url);

The following creates a CacheManager from a configuration in an InputStream.

InputStream fis = new FileInputStream(new File ("src/config/ehcache.xml").getAbsolutePath());
try {
    CacheManager manager = CacheManager.newInstance(fis);
} finally {
    fis.close();
}

Adding and Removing Caches Programmatically

Adding Caches Programmatically

You are not limited to using caches that are placed in the CacheManager configuration. A new cache based on the default configuration can be added to a CacheManager very simply:

manager.addCache(cacheName);

For example, the following adds a cache called testCache to CacheManager called singletonManager. The cache is configured using defaultCache from the CacheManager configuration.

CacheManager singletonManager = CacheManager.create();
singletonManager.addCache("testCache");
Cache test = singletonManager.getCache("testCache");

As shown below, you can also create a new cache with a specified configuration and add the cache to a CacheManager. Note that when you create a new cache, it is not usable until it has been added to a CacheManager.

CacheManager singletonManager = CacheManager.create();
Cache memoryOnlyCache = new Cache("testCache", 5000, false, false, 5, 2);
singletonManager.addCache(memoryOnlyCache);
Cache test = singletonManager.getCache("testCache");

Below is another way to create a new cache with a specified configuration. This example creates a cache called testCache and adds it CacheManager called manager.

// Create a singleton CacheManager using defaults
CacheManager manager = CacheManager.create();
// Create a Cache specifying its configuration.
Cache testCache = new Cache(new CacheConfiguration("testCache", maxEntriesLocalHeap)
    .memoryStoreEvictionPolicy(MemoryStoreEvictionPolicy.LFU)
    .eternal(false)
    .timeToLiveSeconds(60)
    .timeToIdleSeconds(30)
    .diskExpiryThreadIntervalSeconds(0)
    .persistence(new PersistenceConfiguration().strategy(Strategy.LOCALTEMPSWAP)));
manager.addCache(testCache);

For a full list of parameters for a new Cache, see the Cache constructor at http://ehcache.org/xref/net/sf/ehcache/Cache.html.

Removing Caches Programmatically

The following removes the cache called sampleCache1:

CacheManager singletonManager = CacheManager.create();
singletonManager.removeCache("sampleCache1");

Performing Basic Cache Operations

The following examples refer to manager, which is a reference to a CacheManager that contains a cache called sampleCache1.

Obtaining a reference to a Cache

The following obtains a Cache called sampleCache1, which has been preconfigured in the configuration file

Cache cache = manager.getCache("sampleCache1");

Putting an Element in Cache

The following puts an element into a cache

Cache cache = manager.getCache("sampleCache1");
Element element = new Element("key1", "value1");
cache.put(element);

Updating and Element in Cache

The following updates an element in a cache. Even though cache.put( ) is used, Ehcache knows there is an existing element, and considers the put operation as an update for the purpose of notifying cache listeners.

Cache cache = manager.getCache("sampleCache1");
cache.put(new Element("key1", "value1"));
// This updates the entry for "key1"
cache.put(new Element("key1", "value2"));

Getting an Element from Cache

The following gets a Serializable value from an element with a key of key1.

Cache cache = manager.getCache("sampleCache1");
Element element = cache.get("key1");
Serializable value = element.getValue();

The following gets a NonSerializable value from an element with a key of key1.

Cache cache = manager.getCache("sampleCache1");
Element element = cache.get("key1");
Object value = element.getObjectValue();

Removing an Element from Cache

The following removes an element with a key of key1.

Cache cache = manager.getCache("sampleCache1");
cache.remove("key1");

Obtaining Cache Sizes

The following gets the number of elements currently in the cache.

Cache cache = manager.getCache("sampleCache1");
int elementsInMemory = cache.getSize();

The following gets the number of elements currently in the MemoryStore.

Cache cache = manager.getCache("sampleCache1");
long elementsInMemory = cache.getMemoryStoreSize();

The following gets the number of elements currently in the DiskStore.

Cache cache = manager.getCache("sampleCache1");
long elementsInMemory = cache.getDiskStoreSize();

Shutdown the CacheManager

You should shut down a CacheManager after use. It does have a shut-down hook, but it is a best practice to shut it down in your code.

The following shuts down the singleton CacheManager:

CacheManager.getInstance().shutdown();

The following shuts down a CacheManager instance, assuming you have a reference to the CacheManager called manager:

manager.shutdown();

For additional examples, see CacheManagerTest at http://ehcache.org/xref-test/net/sf/ehcache/CacheManagerTest.html.