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

java.lang.Object
  org.pentaho.platform.plugin.services.cache.CacheManager

All Implemented Interfaces:

ICacheManager, ILogoutListener

public class CacheManager
extends java.lang.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

• Most caches require objects that go into the cache as well as their respective object key implement Serializable. It is a safe assumption that both the Key and the Value should implement Serializable.
• Some caches are read-only. Other caches are read-write. What does this mean? It means that once you put an object in the cache, you can't put an object into the cache with the same key. You'd need to remove it first

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(java.lang.String region)
boolean	addCacheRegion(java.lang.String region, java.util.Properties cacheProperties)
boolean	cacheEnabled() Returns the enablement state of the cache.
boolean	cacheEnabled(java.lang.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(java.lang.String region) Clears any data for the specified for a specific region(For example region could be session, global etc)
java.util.Set	getAllEntriesFromRegionCache(java.lang.String region) Get a Set of Map.Entry objects from the cache within a specific region
java.util.Set	getAllKeysFromRegionCache(java.lang.String region) Get a Set of Key objects from the cache within a specific region
java.util.List	getAllValuesFromRegionCache(java.lang.String region) Get a list of values from the cache within a specific region
java.lang.Object	getFromGlobalCache(java.lang.Object key) Gets an object from the cache without translating the passed in key.
java.lang.Object	getFromRegionCache(java.lang.String region, java.lang.Object key) Gets an object from the cache within a specific region
java.lang.Object	getFromSessionCache(IPentahoSession session, java.lang.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(java.lang.Object key, java.lang.Object value) Puts an object directly into the cache without translating the passed in key.
void	putInRegionCache(java.lang.String region, java.lang.Object key, java.lang.Object value) Puts an object directly into the cache of a specific region
void	putInSessionCache(IPentahoSession session, java.lang.String key, java.lang.Object value) Puts an object in the session-specific cache.
void	removeFromGlobalCache(java.lang.Object key) Removes an object from the cache
void	removeFromRegionCache(java.lang.String region, java.lang.Object key) Removes an object from the cache within a specific region
void	removeFromSessionCache(IPentahoSession session, java.lang.String key) Removes a data item from the user session specific cache
void	removeRegionCache(java.lang.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:

• Gets the Pentaho System Settings
• Reads the cache-provider/class element.
• Reads the cache-provider/region element.
• Reads in any properties under cache-provider/properties/*
• Attempts to instance the cache provider classes specified
• Starts the cache (see the org.hibernate.cache.CacheProvider interface)
• Calls the buildCache method (see the org.hibernate.cache.CacheProvider interface)

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(java.lang.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(java.lang.String region,
                              java.util.Properties cacheProperties)

Specified by:

addCacheRegion in interface ICacheManager

addCacheRegion

public boolean addCacheRegion(java.lang.String region)

Specified by:

addCacheRegion in interface ICacheManager

clearRegionCache

public void clearRegionCache(java.lang.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(java.lang.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(java.lang.String region,
                             java.lang.Object key,
                             java.lang.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 java.lang.Object getFromRegionCache(java.lang.String region,
                                           java.lang.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 java.util.List getAllValuesFromRegionCache(java.lang.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 java.util.Set getAllKeysFromRegionCache(java.lang.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 java.util.Set getAllEntriesFromRegionCache(java.lang.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(java.lang.String region,
                                  java.lang.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 java.lang.Object getFromGlobalCache(java.lang.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 java.lang.Object getFromSessionCache(IPentahoSession session,
                                            java.lang.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(java.lang.Object key,
                             java.lang.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,
                              java.lang.String key,
                              java.lang.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(java.lang.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,
                                   java.lang.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