org.pentaho.platform.plugin.services.cache
Class CacheManager

java.lang.Object
  extended by org.pentaho.platform.plugin.services.cache.CacheManager
All Implemented Interfaces:
ICacheManager, ILogoutListener

public class CacheManager
extends Object
implements ICacheManager

This class provides an access point for pluggable caching mechanisms. Right now, it only supports the caching mechanisms implemented in org.hibernate.cache.

To use the cache manager, you need to include the following information in your pentaho.xml.

  
  <cache-provider>
    <class>org.hibernate.cache.xxxxxxxx</class>
    <region>pentahoCache</region>
    <properties>
      <property name="someProperty">someValue</property>
    </properties>
  </cache-provider>
 

The specified class must implement the org.hibernate.cache.CacheProvider interface.

Each implementation of the org.hibernate.cache.CacheProvider has slightly different requirements with respect to the required input parameters - so, please see the classes in that package for more information (available from the Sourceforge Hibernate project). Also, some cache providers (notably the org.hibernate.cache.EhCacheProvider) completely ignore the passed in properties, and only configure themselves by locating a configuration file (e.g. ehcache.xml) on the classpath.

The cache manager supports session-based caching (that is, caching of data that is user-specific) as well as global-based caching (that is, caching of data that is system-wide). To differentiate between session-based and global-based caching, there are different methods that get called depending upon the storage type.

Data that is cached for user sessions require an IPentahoSession object to be passed in. The cache manager uses the IPentahoSession.getId() to classify saved objects underneath a specific user session. No information is actually stored in the user session object. For an example of this, see
putInSessionCache(IPentahoSession session, String key, Object value)

Data that is server-wide (i.e. global) uses different methods for storage/retrieval/management. For an example of this, see
getFromGlobalCache(Object key)

Example Usage:

 String globalCachable = "String to cache";
 String globalCacheKey = "StringKey";
 CacheManager cacheManager = PentahoSystem.getCacheManager();
 cacheManager.putInGlobalCache(globalCacheKey, globalCachable);
 

Important Considerations

Author:
mbatchel
See Also:
CacheProvider, Cache

Field Summary
 
Fields inherited from interface org.pentaho.platform.api.engine.ICacheManager
GLOBAL, SESSION
 
Constructor Summary
CacheManager()
          The constructor performs the following tasks:
 
Method Summary
 boolean addCacheRegion(String region)
           
 boolean addCacheRegion(String region, Properties cacheProperties)
           
 boolean cacheEnabled()
          Returns the enablement state of the cache.
 boolean cacheEnabled(String region)
          Returns the enablement state of the cache.
 void cacheStop()
          Stops the cache by calling the cacheProvider stop method.
 void clearCache()
          Entirely clears the cache.
 void clearRegionCache(String region)
          Clears any data for the specified for a specific region(For example region could be session, global etc)
 Set getAllEntriesFromRegionCache(String region)
          Get a Set of Map.Entry objects from the cache within a specific region
 Set getAllKeysFromRegionCache(String region)
          Get a Set of Key objects from the cache within a specific region
 List getAllValuesFromRegionCache(String region)
          Get a list of values from the cache within a specific region
 Object getFromGlobalCache(Object key)
          Gets an object from the cache without translating the passed in key.
 Object getFromRegionCache(String region, Object key)
          Gets an object from the cache within a specific region
 Object getFromSessionCache(IPentahoSession session, String key)
          Gets an object from the user session specific cache.
 void killSessionCache(IPentahoSession session)
          Removes any session-based data for the specified IPentahoSession.
 void killSessionCaches()
          Removes all cached items that are session-based.
 void onLogout(IPentahoSession session)
           
 void putInGlobalCache(Object key, Object value)
          Puts an object directly into the cache without translating the passed in key.
 void putInRegionCache(String region, Object key, Object value)
          Puts an object directly into the cache of a specific region
 void putInSessionCache(IPentahoSession session, String key, Object value)
          Puts an object in the session-specific cache.
 void removeFromGlobalCache(Object key)
          Removes an object from the cache
 void removeFromRegionCache(String region, Object key)
          Removes an object from the cache within a specific region
 void removeFromSessionCache(IPentahoSession session, String key)
          Removes a data item from the user session specific cache
 void removeRegionCache(String region)
          Clears any data for the specified for a specific region(For example region could be session, global etc) and removed the region from the map
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CacheManager

public CacheManager()
The constructor performs the following tasks:

Method Detail

cacheStop

public void cacheStop()
Description copied from interface: ICacheManager
Stops the cache by calling the cacheProvider stop method. This method should be called either when the VM goes away, or when the web context goes away. This performs required cleanup in the underlying cache implementation. In some cases, failure to stop the cache will cause cached items saved to disk to be un-recoverable.

Specified by:
cacheStop in interface ICacheManager

cacheEnabled

public boolean cacheEnabled(String region)
Description copied from interface: ICacheManager
Returns the enablement state of the cache.

Specified by:
cacheEnabled in interface ICacheManager
Returns:
true if the cache has been initialized and is ready for use.

onLogout

public void onLogout(IPentahoSession session)
Specified by:
onLogout in interface ICacheManager
Specified by:
onLogout in interface ILogoutListener
Parameters:
session - Performs any logout actions based on this session.

addCacheRegion

public boolean addCacheRegion(String region,
                              Properties cacheProperties)
Specified by:
addCacheRegion in interface ICacheManager

addCacheRegion

public boolean addCacheRegion(String region)
Specified by:
addCacheRegion in interface ICacheManager

clearRegionCache

public void clearRegionCache(String region)
Description copied from interface: ICacheManager
Clears any data for the specified for a specific region(For example region could be session, global etc)

Specified by:
clearRegionCache in interface ICacheManager
Parameters:
region - The region whose objects needs to be removed from the cache.

removeRegionCache

public void removeRegionCache(String region)
Description copied from interface: ICacheManager
Clears any data for the specified for a specific region(For example region could be session, global etc) and removed the region from the map

Specified by:
removeRegionCache in interface ICacheManager
Parameters:
region - The region whose objects needs to be removed from the cache.

putInRegionCache

public void putInRegionCache(String region,
                             Object key,
                             Object value)
Description copied from interface: ICacheManager
Puts an object directly into the cache of a specific region

Important note - most cache implementations require both the key and the value to be serializable.

Specified by:
putInRegionCache in interface ICacheManager
key - Object by which the data is indexed
value - The data to store in the cache.

getFromRegionCache

public Object getFromRegionCache(String region,
                                 Object key)
Description copied from interface: ICacheManager
Gets an object from the cache within a specific region

Specified by:
getFromRegionCache in interface ICacheManager
Parameters:
region - the region where the object was put in the cache
key - The key that the data object was stored with
Returns:
The corresponding data object

getAllValuesFromRegionCache

public List getAllValuesFromRegionCache(String region)
Description copied from interface: ICacheManager
Get a list of values from the cache within a specific region

Specified by:
getAllValuesFromRegionCache in interface ICacheManager
Parameters:
region - the region where the object was put in the cache
Returns:
The corresponding list of objects

getAllKeysFromRegionCache

public Set getAllKeysFromRegionCache(String region)
Description copied from interface: ICacheManager
Get a Set of Key objects from the cache within a specific region

Specified by:
getAllKeysFromRegionCache in interface ICacheManager
Parameters:
region - the region where the object was put in the cache
Returns:
The corresponding list of objects

getAllEntriesFromRegionCache

public Set getAllEntriesFromRegionCache(String region)
Description copied from interface: ICacheManager
Get a Set of Map.Entry objects from the cache within a specific region

Specified by:
getAllEntriesFromRegionCache in interface ICacheManager
Parameters:
region - the region where the object was put in the cache
Returns:
The corresponding list of objects

removeFromRegionCache

public void removeFromRegionCache(String region,
                                  Object key)
Description copied from interface: ICacheManager
Removes an object from the cache within a specific region

Specified by:
removeFromRegionCache in interface ICacheManager
Parameters:
region - the region where the object was put in the cache
key - The key that the data object was stored with

cacheEnabled

public boolean cacheEnabled()
Description copied from interface: ICacheManager
Returns the enablement state of the cache.

Specified by:
cacheEnabled in interface ICacheManager
Returns:
true if the cache has been initialized and is ready for use.

clearCache

public void clearCache()
Description copied from interface: ICacheManager
Entirely clears the cache.

Specified by:
clearCache in interface ICacheManager

getFromGlobalCache

public Object getFromGlobalCache(Object key)
Description copied from interface: ICacheManager
Gets an object from the cache without translating the passed in key.

Specified by:
getFromGlobalCache in interface ICacheManager
Parameters:
key - The key that the data object was stored with
Returns:
The corresponding data object

getFromSessionCache

public Object getFromSessionCache(IPentahoSession session,
                                  String key)
Description copied from interface: ICacheManager
Gets an object from the user session specific cache. If the object doesn't exist in the cache, null is returned.

Specified by:
getFromSessionCache in interface ICacheManager
Parameters:
session - The users IPentahoSession
key - The key that maps to the data to get from the cache
Returns:
Object that was stored in the cache

killSessionCache

public void killSessionCache(IPentahoSession session)
Description copied from interface: ICacheManager
Removes any session-based data for the specified IPentahoSession.

Specified by:
killSessionCache in interface ICacheManager
Parameters:
session - The session whose objects needs to be removed from the cache.

killSessionCaches

public void killSessionCaches()
Description copied from interface: ICacheManager
Removes all cached items that are session-based.

Specified by:
killSessionCaches in interface ICacheManager

putInGlobalCache

public void putInGlobalCache(Object key,
                             Object value)
Description copied from interface: ICacheManager
Puts an object directly into the cache without translating the passed in key.

Important note - most cache implementations require both the key and the value to be serializable.

Specified by:
putInGlobalCache in interface ICacheManager
Parameters:
key - Object by which the data is indexed
value - The data to store in the cache.

putInSessionCache

public void putInSessionCache(IPentahoSession session,
                              String key,
                              Object value)
Description copied from interface: ICacheManager
Puts an object in the session-specific cache. The session specified must have a valid session id.

Take special care that, in a TestCase, you don't have multiple StandaloneSession objects with the same session key. Consider using UUIDUtil to generate a unique sessionId for each standalone session.

Specified by:
putInSessionCache in interface ICacheManager
Parameters:
session - The users IPentahoSession
key - The key by which you want to retrieve the data back out
value - The data item to place into the cache

removeFromGlobalCache

public void removeFromGlobalCache(Object key)
Description copied from interface: ICacheManager
Removes an object from the cache

Specified by:
removeFromGlobalCache in interface ICacheManager
Parameters:
key - The key that the data object was stored with

removeFromSessionCache

public void removeFromSessionCache(IPentahoSession session,
                                   String key)
Description copied from interface: ICacheManager
Removes a data item from the user session specific cache

Specified by:
removeFromSessionCache in interface ICacheManager
Parameters:
session - The users IPentahoSession
key - The key that maps to the value needing removed