Using PentahoSystem ICacheManager

This document describes how to use ICacheManager in your plugin or extension of the BI Platform. The default implementation of the ICacheManager interface supports cache regions (segmentation of keys along a particular use-case). The standard regions are GLOBAL (putInGlobalCache / getFromGlobalCache), and SESSION (putInSessionCache / getFromSessionCache). Plugins are permitted to use these regions as they are, or they can define their own cache region (addCacheRegion). When a plugin defines a cache region, the plugin is responsible for the life-cycle of that cache region. That is, the startup and shutdown of that region is the responsibility of the plugin and should be managed from a lifecycle listener.

A plugin would need to define its own cache region if the plugin needed a separate cache area that needs to be flushed independently from the GLOBAL or SESSION caches. Be careful though to never put user-session specific data outside the SESSION cache. The SESSION cache has special session-expiration code that clears the SESSION cache when a user logs out (or the HTTPSession times out).

Since the present ICacheManager doesn't yet support session-segmented independent regions, there are two choices for implementing this capability:

• As shown in http://jira.pentaho.com/browse/CDF-53, you could incorporate a combination ILogoutListener with your LifecycleListener. This would let you have a doubly-segmented cache that would require a small bit of extra management.
• You could use creative key-specification and use the existing SESSION cache. In this way, when the session expires, all settings will naturally be removed from the cache. This gets ugly when multiple session-caches need flushed at the same time though.

Before using PentahoSystem's ICacheManager, you must configure ehcache to contain the cache regions. Otherwise, they will default to the defaultCache.

The ehcache.xml file, which ends up located in pentaho/WEB-INF/classes/ehcache.xml, is in SVN at:
http://source.pentaho.org/svnroot/bi-platform-v2/trunk/bi-platform-engine-services/res/ehcache/ehcache.xml

Accessing the ICacheManager:

ICacheManager cacheMgr = PentahoSystem.getCacheManager(pentahoSession);

Creating a cache:
* Note - this should be done in the startup of your lifecycle listener.

if(!cacheMgr.cacheEnabled("your_plugin_cache")) {
      cacheMgr.addCacheRegion("your_plugin_cache");
}

Removing a cache:

\* Note - this should be done in the shutdown of your lifecycle listener.
if ( (cacheMgr != null) && (cacheMgr.cacheEnabled("your_plugin_cache")) ) {
  cacheMgr.removeRegionCache("your_plugin_cache");
}

Clearing the cache:

if(cacheMgr.cacheEnabled("your_plugin_cache")) {
    cacheMgr.clearRegionCache("your_plugin_cache");
}

Putting items in the cache:

* Note: All objects in the cache must implement and be serializable.  Otherwise errors will occur when ehcache attempts to store cached items to disk.

Object myObject = getMyObject();
cacheMgr.putInRegionCache("your_plugin_cache", "cache_item_1", myObject);

Getting items from the cache:

Object myObject = cacheMgr.getFromRegionCache("your_plugin_cache", "cache_item_1");

Getting all items from the cache:

List<MyClass> catalogs = (List<MyClass>)cacheMgr.getAllValuesFromRegionCache("your_plugin_cache");

Here is a link to the ICacheManager source:
http://source.pentaho.org/svnroot/bi-platform-v2/trunk/bi-platform-api/src/org/pentaho/platform/api/engine/ICacheManager.java