Going Through the Lifecycle of a Cache
Java configuration is most easily achieved through the use of builders that offer a fluent API.
The canonical way of dealing with a Cache is through a CacheManager. Creating, using and closing a cache with CacheManager is illustrated in this example:
CacheManager cacheManager
= CacheManagerBuilder.newCacheManagerBuilder() // <1>
.withCache("preConfigured",
CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class,
String.class, ResourcePoolsBuilder.heap(10))) // <2>
.build(); // <3>
cacheManager.init(); // <4>
Cache<Long, String> preConfigured = cacheManager.getCache("preConfigured",
Long.class, String.class); // <5>
Cache<Long, String> myCache =
cacheManager.createCache("myCache", // <6>
CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class,
String.class, ResourcePoolsBuilder.heap(10)));
myCache.put(1L, "da one!"); // <7>
String value = myCache.get(1L); // <8>
cacheManager.removeCache("preConfigured"); // <9>
cacheManager.close(); // <10>
The following list items refer to the commented numbers in the code.
<1> Using the Builders
The static method org.ehcache.config.builders.CacheManagerBuilder.newCacheManagerBuilder returns a new org.ehcache.config.builders.CacheManagerBuilder instance.
<2> Declare a cache configuration
Use the builder to define a Cache with alias "preConfigured". This cache will be created when cacheManager.build() is invoked on the actual CacheManager instance.
The first String argument is the cache alias, which is used to retrieve the cache from the CacheManager.
The second argument, org.ehcache.config.CacheConfiguration, is used to configure the Cache.
In this case, the static newCacheConfigurationBuilder() method is used on org.ehcache.config.builders.CacheConfigurationBuilder to create a default configuration.
<3> Instantiate a CacheManager
Invoking build() returns a fully instantiated, but uninitialized, CacheManager ready to use.
<4> Initialize the CacheManager
Before using the CacheManager it needs to be initialized, which can be done in 1 of 2 ways:
Calling
CacheManager.init() on the
CacheManager instance, or
Calling the
CacheManagerBuilder.build(boolean init) method with the boolean parameter set to true.
<5> Retrieving the preConfigured Cache and Type-Safety
A cache is retrieved by passing its alias, key type and value type to the CacheManager. For instance, to obtain the cache declared in step 2 you need its alias=preConfigured, keyType=Long.class and valueType=String.class.
Asking for both key and value types to be passed in ensures type-safety. Should these differ from the ones expected, the CacheManager throws a ClassCastException early in the application’s lifecycle. This also guards the Cache from being polluted by random types.
<6> Create a new Cache
The CacheManager can also be used to create new Cache as needed.
Just as in step 2, it requires passing an alias as well as a CacheConfiguration.
The instantiated and fully initialized Cache added will be returned and/or accessed through the CacheManager.getCache API.
<7> Store and ...
The newly added Cache can now be used to store entries, which are comprised of key value pairs. The put method's first parameter is the key and the second parameter is the value. Remember the key and value types must be the same types as those defined in the CacheConfiguration. Additionally the key must be unique and is only associated with one value.
<8> Retrieve data
A value is retrieved from a cache by calling the cache.get(key) method. It only takes one parameter which is the key, and returns the value associated with that key. If there is no value associated with that key then null is returned.
<9> Remove and close a given Cache
With CacheManager.removeCache(String) any given Cache can be removed.
The CacheManager will not only remove its reference to the Cache, but will also close it. The Cache releases all locally held transient resources (such as memory). References to this Cache become unusable.
<10> Close all Cache instances
In order to release all transient resources (memory, threads, ...) that a CacheManager provides to its managed Cache instances, CacheManager.close() needs to be invoked. This closes all Cache instances known at the time.