Package com.microstrategy.utils.cache

Class CacheBase

java.lang.Object

com.microstrategy.utils.cache.CacheBase

All Implemented Interfaces:

Cache

Direct Known Subclasses:

CustomizationsAwareCache, EsriMapCache, MapBoxBoundaryCache, MapShapeCache, MSIRefreshClusterMembershipCache, ProjectCacheBase, RandomNumberMap, RefineServerPortCache, RepositorySettingsCache, ServerCacheBase, SessionCacheBase

public abstract class CacheBase
extends java.lang.Object
implements Cache

Base class for caches.

Since:

MicroStrategy Web 7.3.1 or earlier

Field Summary

Fields

Modifier and Type	Field	Description
java.lang.String	alias	Cache alias.
static int	DEFAULT_FILE_REFRESH_TIME	Refresh time constant indicating that default file refreshing time from the CacheRegistry shall be used for this cache.
static int	DEFAULT_REFRESH_TIME	Refresh time constant indicating that default refresh time from the CacheRegistry shall be used for this cache.
static int	DEFAULT_STATISTIC_TIME	Statistic time constant indicating that default statistic time from the CacheRegistry shall be used for this cache.
static int	DEFAULT_SYS_TIMEOUT
static int	DEFAULT_USER_TIMEOUT	Timeout constant indicating that default timeout value from the CacheRegistry shall be used for this cache.
static java.lang.Object	NO_KEY	This constant is returned from getKey(CacheHint) if the hint object does not contain enough information to build the key but it is still possible to load the object from the persistent storage.
static int	NO_REFRESH	Refresh time constant indicating that cache members are never automatically reloaded.
static int	NO_STATISTIC	Statistic time constant indicating that cache shall not automatically log statistic.
static int	NO_TIMEOUT	Timeout constant indicating that cache members shall never timeout.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	CacheBase(java.lang.String pName, boolean useSoftReferences, int pTimeout, int pRefreshTime)	Constructs a cache with specified name and soft reference flag.
protected	CacheBase(java.lang.String pName, boolean useSoftReferences, int pTimeout, int pRefreshTime, java.lang.String pAlias)

Method Summary

Modifier and Type	Method	Description
protected boolean	canUpdate(CacheHint hint)	Overridable.
void	clear()	Clears the cache - all entries are removed.
void	close()	Un-register cache from the cache registry.
protected void	configure(java.util.Properties prop)
boolean	contains(CacheHint hint)
void	delete(CacheHint hint)	Removes object from the cache and persistent storage
java.lang.Object	get(CacheHint hint)	get returns an unexpired cache value.
protected abstract java.lang.Object	getKey(CacheHint hint)	Overridable.
java.lang.String	getName()	Returns cache name.
int	getRefreshTime()	Returns cache refresh time in seconds.
int	getStatisticTime()	Returns the statistic frequency in seconds.
int	getTimeout()	Returns cache timeout in seconds.
java.lang.Object	getWithoutRefresh(CacheHint hint)	getWithoutRefresh checks to see if the cache is unexpired.
protected abstract java.lang.Object	load(CacheHint hint)	Overridable.
void	logStatistic()	Writes cache statistic message to the log.
void	onHintClose(CacheHint hint)	This method is supposed to be called by the hint object when it is closed.
protected void	onTimer()	This method is periodically called by the cache registry.
void	put(CacheHint hint, java.lang.Object ob)	Puts the object in the cache.
java.lang.Object	refresh(CacheHint hint)	Re-loads object from the persistent storage
protected java.lang.Object	reLoad(CacheHint hint, java.lang.Object ob)	Overridable.
void	remove(CacheHint hint)	Removes an object from the cache.
void	save(CacheHint hint, java.lang.Object ob)	Puts the object in the cache and stores it in the memory.
void	setRefreshTime(int value)	Sets cache refresh time in seconds.
void	setStatisticTime(int value)	Sets the statistic frequency in seconds.
void	setTimeout(int value)	Sets cache timeout in seconds.
int	size()	Returns cache size.
protected void	store(CacheHint hint, java.lang.Object ob)	Overridable.
protected void	unLoad(CacheHint hint)	Overridable.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

alias

public java.lang.String alias

Cache alias. Short version of name, used for things like state persistence. Must be unique within application.

Since:

MicroStrategy Web 9.0.0

NO_TIMEOUT

public static final int NO_TIMEOUT

Timeout constant indicating that cache members shall never timeout.

See Also:

Constant Field Values

DEFAULT_USER_TIMEOUT

public static final int DEFAULT_USER_TIMEOUT

Timeout constant indicating that default timeout value from the CacheRegistry shall be used for this cache.

See Also:

Constant Field Values

DEFAULT_SYS_TIMEOUT

public static final int DEFAULT_SYS_TIMEOUT

See Also:

Constant Field Values

NO_REFRESH

public static final int NO_REFRESH

Refresh time constant indicating that cache members are never automatically reloaded.

See Also:

Constant Field Values

DEFAULT_REFRESH_TIME

public static final int DEFAULT_REFRESH_TIME

Refresh time constant indicating that default refresh time from the CacheRegistry shall be used for this cache.

See Also:

CacheRegistry.getDefaultRefreshTime(), Constant Field Values

DEFAULT_FILE_REFRESH_TIME

public static final int DEFAULT_FILE_REFRESH_TIME

Refresh time constant indicating that default file refreshing time from the CacheRegistry shall be used for this cache.

Since:

MicroStrategy Web 9.0.0

See Also:

CacheRegistry.getDefaultFileRefreshTime(), Constant Field Values

NO_STATISTIC

public static final int NO_STATISTIC

Statistic time constant indicating that cache shall not automatically log statistic.

See Also:

Constant Field Values

DEFAULT_STATISTIC_TIME

public static final int DEFAULT_STATISTIC_TIME

Statistic time constant indicating that default statistic time from the CacheRegistry shall be used for this cache.

See Also:

Constant Field Values

NO_KEY

public static final java.lang.Object NO_KEY

This constant is returned from getKey(CacheHint) if the hint object does not contain enough information to build the key but it is still possible to load the object from the persistent storage. For example, if the WebIServerSession object contains the session ID, but does not contain either server or project name makes it impossible to cache the corresponding project-level objects but it is possible to load them.

Whenever the cache receives this constant it will always invoke load(CacheHint), i.e. effectively bypassing the cache.

Constructor Detail

CacheBase

protected CacheBase(java.lang.String pName,
                    boolean useSoftReferences,
                    int pTimeout,
                    int pRefreshTime)
             throws java.lang.IllegalArgumentException

Constructs a cache with specified name and soft reference flag.

Parameters:

pName - cache name

useSoftReferences - controls whether hard or soft references shall be used between proxies and cached objects.

Throws:

java.lang.IllegalArgumentException - if the cache with specified name already exosts/

CacheBase

protected CacheBase(java.lang.String pName,
                    boolean useSoftReferences,
                    int pTimeout,
                    int pRefreshTime,
                    java.lang.String pAlias)
             throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

Since:

MicroStrategy Web 9.0.0

Method Detail

configure

protected void configure(java.util.Properties prop)

getName

public java.lang.String getName()

Description copied from interface: Cache

Returns cache name.

Specified by:

getName in interface Cache

Returns:

cache name.

get

public java.lang.Object get(CacheHint hint)
                     throws CacheException

get returns an unexpired cache value. If the cache was expired at the time of the call, then the cache is refreshed. If the cache was unexpired at the time of the call, then the cache value is used (without any need to refresh the cache). If the cache cannot be refreshed, then a CacheExceptin is thrown. null may be returned if the hint cannot be resolved.

Specified by:

get in interface Cache

Parameters:

hint -

Returns:

the unexpired cache or null

Throws:

CacheException - when the cache cannot be refreshed

getWithoutRefresh

public java.lang.Object getWithoutRefresh(CacheHint hint)

getWithoutRefresh checks to see if the cache is unexpired. If the cache is unexpired the cache value is returned. If the cache is expired, the cache is not refreshed; instead null is returned.

Parameters:

hint -

Returns:

the cache if unexpired, otherwise it returns null

put

public void put(CacheHint hint,
                java.lang.Object ob)
         throws CacheException

Description copied from interface: Cache

Puts the object in the cache. If cache already contains object corresponding to the specified hint it will be replaced with the new one.

Specified by:

put in interface Cache

Parameters:

hint - the hint object.

ob - object to be cached

Throws:

CacheException - if attempt to extract key from the hint failed

remove

public void remove(CacheHint hint)
            throws CacheException

Description copied from interface: Cache

Removes an object from the cache.

Specified by:

remove in interface Cache

Parameters:

hint - the hint object.

Throws:

CacheException - Thrown when error occurs during removing the object.

delete

public void delete(CacheHint hint)
            throws CacheException

Description copied from interface: Cache

Removes object from the cache and persistent storage

Specified by:

delete in interface Cache

Parameters:

hint - the hint object.

Throws:

CacheException - if attempt to extract key from the hint failed or if attempt to remove obect from the persistent storage failed

save

public void save(CacheHint hint,
                 java.lang.Object ob)
          throws CacheException

Description copied from interface: Cache

Puts the object in the cache and stores it in the memory. Normally this method will be called after application obtained an object from the cache and modified it. But it is also possible to use this method to replace cached object with another one or to add to the cache and to the persistent storage a new object.

Specified by:

save in interface Cache

Parameters:

hint - the hint object.

ob - object to be cached

Throws:

CacheException - if attempt to extract key from the hint failed or if attempt to store obect in the persistent storage failed

refresh

public java.lang.Object refresh(CacheHint hint)
                         throws CacheException

Description copied from interface: Cache

Re-loads object from the persistent storage

Specified by:

refresh in interface Cache

Parameters:

hint - the hint object.

Returns:

cached object. Different cache implementations can either re-load data in the existing object or create a new one.

Throws:

CacheException - if attempt to extract key from the hint failed or if attempt to re-load obect from the persistent storage failed

close

public void close()

Description copied from interface: Cache

Un-register cache from the cache registry. Cache shall not be used after this call.

Specified by:

close in interface Cache

Since:

MicroStrategy Web 8.0.0

onHintClose

public void onHintClose(CacheHint hint)

Description copied from interface: Cache

This method is supposed to be called by the hint object when it is closed. Cache implementations shall use this call to perform proper cache cleanup.

Specified by:

onHintClose in interface Cache

Parameters:

hint - the hint object.

setRefreshTime

public void setRefreshTime(int value)

Sets cache refresh time in seconds. This property determins time interval between consequtive automatic re-loads of cached objects.

Parameters:

value - refresh time in seconds.

getRefreshTime

public int getRefreshTime()

Returns cache refresh time in seconds. This property determines the time interval between consecutive automatic re-loads of cached objects.

Returns:

refresh time in seconds.

setTimeout

public void setTimeout(int value)

Sets cache timeout in seconds. This property determines for how long cached object can remain in memory without being used.

Parameters:

value - timeout in seconds.

getTimeout

public int getTimeout()

Returns cache timeout in seconds. This property determines for how long cached object can remain in memory without being used.

Returns:

timeout in seconds.

setStatisticTime

public void setStatisticTime(int value)

Sets the statistic frequency in seconds. Notice that because the statistic is logged during onTimer event it will never be logged more often then CacheRegistry.cleanupTime value regardless of this property value.

Parameters:

value - log frequency in seconds.

getStatisticTime

public int getStatisticTime()

Returns the statistic frequency in seconds.

Returns:

statistic frequency in seconds..

size

public int size()

Returns cache size.

Returns:

cache size.

logStatistic

public void logStatistic()

Writes cache statistic message to the log. The message level is INFO. It contains the following information:

Get count	-	Total number of get requests processed by the cache.
Load count	-	Total number of load/reload operations performed by the cache.
Hit rate	-	The percentage of get requests satisfied from the memory to all get requests
GC Count	-	Total number of soft-referenced cached objects removed by the Garbage Collector
GC rate	-	The percentage of load/reload operations caused by the GC to all load/reload operations

onTimer

protected void onTimer()

This method is periodically called by the cache registry. It loops through cached objects and removes not-used ones.

getKey

protected abstract java.lang.Object getKey(CacheHint hint)
                                    throws CacheException

Overridable. Extracts from the hint object the key that shall be used to identify the cached object.

Parameters:

hint - the hint object.

Returns:

the key

Throws:

CacheException - if somethig gos wrong.

load

protected abstract java.lang.Object load(CacheHint hint)
                                  throws CacheException

Overridable. Creates a new cached object instance and populates it with data from the persistent storage. In case the object not found in the persistent storage the implementation can return either null or a dummy object.

Parameters:

hint - the hint object.

Returns:

the object or null.

Throws:

CacheException - if somethig gos wrong.

reLoad

protected java.lang.Object reLoad(CacheHint hint,
                                  java.lang.Object ob)
                           throws CacheException

Overridable. Re-populates cached object with data from persistent storage. Implementation of this method can re-load the object "in-place" or it can create another object.

Parameters:

hint - the hint object.

Returns:

the object or null.

Throws:

CacheException - if somethig gos wrong.

store

protected void store(CacheHint hint,
                     java.lang.Object ob)
              throws CacheException

Overridable. Saves cached object in the persistent storage.

Parameters:

hint - the hint object.

ob - the object to save.

Throws:

CacheException - if somethig gos wrong.

unLoad

protected void unLoad(CacheHint hint)
               throws CacheException

Overridable. Removes object from the persistent storage

Parameters:

hint - the hint object.

Throws:

CacheException - if somethig gos wrong.

canUpdate

protected boolean canUpdate(CacheHint hint)
                     throws CacheException

Overridable. Returns true if the hint allows updates. Default implementation always returns true.

Parameters:

hint - the hint object.

Returns:

true if the hint allows updates.

Throws:

CacheException

clear

public void clear()

Description copied from interface: Cache

Clears the cache - all entries are removed.

Specified by:

clear in interface Cache

Since:

MicroStrategy Web 7.5.1 TQMS 709199, clean both usedList and members while clear.

See Also:

Cache.clear()

contains

public boolean contains(CacheHint hint)
                 throws CacheException

Specified by:

contains in interface Cache

Throws:

CacheException