atg.service.cache
Class Cache

java.lang.Object
  atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
      atg.nucleus.GenericService
          atg.service.cache.Cache

All Implemented Interfaces:

atg.naming.AbsoluteNameable, NameContextBindingListener, NameContextElement, atg.naming.NameContextParentable, NameResolver, AdminableService, atg.nucleus.Configured, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, java.io.Serializable, java.util.EventListener

Direct Known Subclasses:

DocumentCache

public class Cache
extends GenericService
implements java.io.Serializable

This service is a general-purpose LRU cache.

Clients of this service must first implement CacheAdapter, which will be called by this class to maintain elements as related to keys. The Cache class will then take care of maintaining the cache.

Most recent changes address multithreading problems. Specifically, when multiple threads are all requesting the object for a single key for the first time, the adapter is only asked to do the work once. Likewise, the same object is guaranteed to be returned to each thread in this scenario.

This cache class may be used in non-pass-through manner, by simply not setting the cacheAdapter property. Memory restrictions will be ignored, and get() calls will return null Previously, if multiple threads all asked for an object that wasn't in cache and all used the same key, each thread would receive functionally similar but unique objects from the cache. This is a performance hit, and can also cause havoc with applications that expect all threads to receive a single object from cache.

See Also:

Serialized Form

Field Summary

static java.lang.String

CLASS_VERSION

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

Cache()
Constructor

Method Summary

boolean	contains(java.lang.Object pKey) Checks for the presence of the object with the specified key, without invoking the CacheAdapter.
boolean	contains(java.lang.Object[] pKeys) Returns false unless all specified keys refer to objects in the cache.
java.lang.String	dump()
void	dump(java.io.PrintStream aStream) meant to be a debugging aid, will print current key/value pairs the mMap hashtable to the supplied PrintStream, a prime example of which is System.out
void	flush() Flushes all entries from the cache, leaving it empty.
java.lang.Object	get(java.lang.Object pKey) Searches the cache for the object with the specified key.
java.lang.Object[]	get(java.lang.Object[] pKeys) Searches the cache for the objects with the specified keys.
int	getAccessCount() Returns the total number of accesses
java.util.Iterator	getAllElements() Returns all elements in this Cache.
java.util.Iterator	getAllKeys() Returns all elements in this Cache.
java.util.Iterator	getAllKeysOrdered(boolean pLatestFirst) Returns all elements in this Cache ordered by entry creation time.
CacheAdapter	getCacheAdapter() The Adapter used to create entries in the cache
atg.service.cache.CacheRemovalListener	getCacheRemovalListener() The CacheRemovalListener notified when objects are removed from this cache
boolean	getEnablePartialKeyInvalidation() Whether this cache should invalidate by part of the key.
int	getHitCount() Returns the number of cache hits
double	getHitRatio() Returns the number of cache hits / total number of cache accesses
int[]	getKeyPartsForInvalidation() Which key parts should be used for invalidation.
int	getMaximumCacheEntries() Returns the maximum number of elements in the cache. 0 = Cache nothing, but continue to get objects from the CacheAdapter -1 = Unlimited
int	getMaximumCacheSize() Returns the maximum memory size of the cache.
long	getMaximumEntryLifetime() Returns the maximum number of msec that an entry will live in the cache. 0 = Cache nothing, but continue to get objects from the CacheAdapter -1 = Unlimited
int	getMaximumEntrySize() Returns the maximum memory size of a single entry in the cache.
int	getNumCacheEntries() Returns the number of entries currently in the cache
int	getNumKeyParts() The number of key parts this cache expects.
int	getSize() Returns the number of entries currently in the cache
int	getTimeoutCount() Returns the number of times entries were invalidated because they were out-of-date.
double	getUsedCapacity() Returns the ratio of cache entries to maximum cache entries.
int	getUsedMemory() Returns the amount of memory taken up by the entries in the cache (includes keys).
double	getUsedMemoryCapacity() Returns the ratio of memory size to maximum memory size
java.util.Iterator	getValidKeysOrdered(boolean pLatestFirst) Returns all elements in this Cache ordered by entry creation time.
protected boolean	isExpiredValueStillGood(java.lang.Object key, java.lang.Object pValue) Return whether the expired value is still good.
static void	main(java.lang.String[] args)
void	put(java.lang.Object pKey, java.lang.Object pValue) Puts an entry into the cache, placing that entry at the front of the LRU list.
boolean	remove(java.lang.Object pKey) Invalidates the entry with the given key.
boolean	remove(java.lang.Object pKey, java.lang.Object pNewValue) Invalidates the entry with the given key.
int	removeByPartialKey(int pPartialKeyIndex, java.lang.Object pPartialKeyValue) Removes by partial key.
void	setCacheAdapter(CacheAdapter pAdapter) The Adapter used to create entries in the cache
void	setCacheRemovalListener(atg.service.cache.CacheRemovalListener pRemovalListener) The CacheRemovalListener notified when objects are removed from this cache
void	setEnablePartialKeyInvalidation(boolean pEnablePartialKeyInvalidation) Whether this cache should invalidate by part of the key.
void	setKeyPartsForInvalidation(int[] pKeyPartsForInvalidation) Which key parts should be used for invalidation.
void	setMaximumCacheEntries(int pMaximumCacheEntries) Sets the maximum number of elements in the cache.
void	setMaximumCacheSize(int pMaximumCacheSize) Sets the maximum memory size of the cache.
void	setMaximumEntryLifetime(long pMaximumEntryLifetime) Sets the maximum number of msec that an entry will live in the cache. 0 = Cache nothing, but continue to get objects from the CacheAdapter -1 = Unlimited
void	setMaximumEntrySize(int pMaximumEntrySize) Sets the maximum memory size of a single entry in the cache.
void	setNumKeyParts(int pNumKeyParts) The number of key parts this cache expects.
java.lang.Object	setWaiterAndGetValue(java.lang.Object pKey, boolean pCacheIt) this method just gets an object from a cacheadapter, but in addition sets waiter semaphores to prevent the duplication of cache adapter work.

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStartService, doStopService, getAbsoluteName, getAdminServlet, getAdminServletOutputStreamEncoding, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isAdminServletUseServletOutputStream, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setAdminServletOutputStreamEncoding, setAdminServletUseServletOutputStream, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static final java.lang.String CLASS_VERSION

See Also:

Constant Field Values

Constructor Detail

Cache

public Cache()

Constructor

Method Detail

setWaiterAndGetValue

public java.lang.Object setWaiterAndGetValue(java.lang.Object pKey,
                                             boolean pCacheIt)
                                      throws java.lang.Exception

this method just gets an object from a cacheadapter, but in addition sets waiter semaphores to prevent the duplication of cache adapter work.

Parameters:

pKey - the key to use for fetching from the CacheAdapter

pCacheIt - whether to put the object in the cache.

Returns:

the object from the appropriate cacheAdapter

Throws:

java.lang.Exception

contains

public boolean contains(java.lang.Object pKey)

Checks for the presence of the object with the specified key, without invoking the CacheAdapter. No exceptions!

contains

public boolean contains(java.lang.Object[] pKeys)

Returns false unless all specified keys refer to objects in the cache.

dump

public void dump(java.io.PrintStream aStream)

meant to be a debugging aid, will print current key/value pairs the mMap hashtable to the supplied PrintStream, a prime example of which is System.out

dump

public java.lang.String dump()

get

public java.lang.Object get(java.lang.Object pKey)
                     throws java.lang.Exception

Searches the cache for the object with the specified key. If not found, then it uses the CacheAdapter to retrieve one. Returns null if unable to obtain the cached object.

Throws:

java.lang.Exception

get

public java.lang.Object[] get(java.lang.Object[] pKeys)
                       throws java.lang.Exception

Searches the cache for the objects with the specified keys. Any not found in the cache are retrieved by the CacheAdapter. Returns an array of all retrieved items (null for any which could not be retrieved). The array of objects returned is ordered to correspond with the order of the array of keys passed in.

Throws:

java.lang.Exception

isExpiredValueStillGood

protected boolean isExpiredValueStillGood(java.lang.Object key,
                                          java.lang.Object pValue)

Return whether the expired value is still good. May be overridden by subclasses.

Parameters:

pKey - the key the corresponds to the value

pValue - the value to check

put

public void put(java.lang.Object pKey,
                java.lang.Object pValue)

Puts an entry into the cache, placing that entry at the front of the LRU list.

remove

public boolean remove(java.lang.Object pKey)

Invalidates the entry with the given key. (Called on get when the entry has timed out, on put if the entry is pre-existing in the cache, and also on put for each lru entry until max size and max entries requirements are met.)

Returns:

true if the item was found and removed

remove

public boolean remove(java.lang.Object pKey,
                      java.lang.Object pNewValue)

Invalidates the entry with the given key. (Called on get when the entry has timed out, on put if the entry is pre-existing in the cache, and also on put for each lru entry until max size and max entries requirements are met.)

Returns:

true if the item was found and removed

flush

public void flush()

Flushes all entries from the cache, leaving it empty.

removeByPartialKey

public int removeByPartialKey(int pPartialKeyIndex,
                              java.lang.Object pPartialKeyValue)

Removes by partial key.

Parameters:

pPartialKeyIndex - index of the partial key to remove, should be >= 0 and < numKeyParts

pPartialKeyValue - value of the partial key to remove

Returns:

the number of items removed

getCacheAdapter

public CacheAdapter getCacheAdapter()

The Adapter used to create entries in the cache

setCacheAdapter

public void setCacheAdapter(CacheAdapter pAdapter)

The Adapter used to create entries in the cache

getCacheRemovalListener

public atg.service.cache.CacheRemovalListener getCacheRemovalListener()

The CacheRemovalListener notified when objects are removed from this cache

setCacheRemovalListener

public void setCacheRemovalListener(atg.service.cache.CacheRemovalListener pRemovalListener)

The CacheRemovalListener notified when objects are removed from this cache

getMaximumCacheEntries

public int getMaximumCacheEntries()

Returns the maximum number of elements in the cache.
0 = Cache nothing, but continue to get objects from the CacheAdapter
-1 = Unlimited

setMaximumCacheEntries

public void setMaximumCacheEntries(int pMaximumCacheEntries)

Sets the maximum number of elements in the cache.
0 = Cache nothing, but continue to get objects from the CacheAdapter
-1 = Unlimited

getMaximumCacheSize

public int getMaximumCacheSize()

Returns the maximum memory size of the cache.
0 = Cache nothing, but continue to get objects from the CacheAdapter
-1 = Unlimited

setMaximumCacheSize

public void setMaximumCacheSize(int pMaximumCacheSize)

Sets the maximum memory size of the cache.
0 = Cache nothing, but continue to get objects from the CacheAdapter
-1 = Unlimited

getMaximumEntrySize

public int getMaximumEntrySize()

Returns the maximum memory size of a single entry in the cache.
0 = Cache nothing, but continue to get objects from the CacheAdapter
-1 = Unlimited

setMaximumEntrySize

public void setMaximumEntrySize(int pMaximumEntrySize)

Sets the maximum memory size of a single entry in the cache.
0 = Cache nothing, but continue to get objects from the CacheAdapter
-1 = Unlimited

getMaximumEntryLifetime

public long getMaximumEntryLifetime()

Returns the maximum number of msec that an entry will live in the cache.
0 = Cache nothing, but continue to get objects from the CacheAdapter
-1 = Unlimited

setMaximumEntryLifetime

public void setMaximumEntryLifetime(long pMaximumEntryLifetime)

Sets the maximum number of msec that an entry will live in the cache.
0 = Cache nothing, but continue to get objects from the CacheAdapter
-1 = Unlimited

getEnablePartialKeyInvalidation

public boolean getEnablePartialKeyInvalidation()

Whether this cache should invalidate by part of the key. When set to true, MultiPartCacheKey objects should be passed in as keys.

setEnablePartialKeyInvalidation

public void setEnablePartialKeyInvalidation(boolean pEnablePartialKeyInvalidation)

Whether this cache should invalidate by part of the key. When set to true, MultiPartCacheKey objects should be passed in as keys.

getNumKeyParts

public int getNumKeyParts()

The number of key parts this cache expects. Only used if enablePartialKeyInvalidation == true;

setNumKeyParts

public void setNumKeyParts(int pNumKeyParts)

The number of key parts this cache expects. Only used if enablePartialKeyInvalidation == true;

getKeyPartsForInvalidation

public int[] getKeyPartsForInvalidation()

Which key parts should be used for invalidation. For example, setting to [0, 2, 3] would use first, third, and fourth key parts for invalidation. Leaving this null means that all parts are available for invalidation. Empty array means no parts are available.

setKeyPartsForInvalidation

public void setKeyPartsForInvalidation(int[] pKeyPartsForInvalidation)

Which key parts should be used for invalidation. For example, setting to [0, 2, 3] would use first, third, and fourth key parts for invalidation. Leaving this null means that all parts are available for invalidation. Empty array means no parts are available.

getSize

public int getSize()

Returns the number of entries currently in the cache

getNumCacheEntries

public int getNumCacheEntries()

Returns the number of entries currently in the cache

getUsedCapacity

public double getUsedCapacity()

Returns the ratio of cache entries to maximum cache entries.

getUsedMemory

public int getUsedMemory()

Returns the amount of memory taken up by the entries in the cache (includes keys).

getUsedMemoryCapacity

public double getUsedMemoryCapacity()

Returns the ratio of memory size to maximum memory size

getAccessCount

public int getAccessCount()

Returns the total number of accesses

getHitCount

public int getHitCount()

Returns the number of cache hits

getHitRatio

public double getHitRatio()

Returns the number of cache hits / total number of cache accesses

getTimeoutCount

public int getTimeoutCount()

Returns the number of times entries were invalidated because they were out-of-date.

getAllElements

public java.util.Iterator getAllElements()

Returns all elements in this Cache.

getAllKeys

public java.util.Iterator getAllKeys()

Returns all elements in this Cache.

getValidKeysOrdered

public java.util.Iterator getValidKeysOrdered(boolean pLatestFirst)

Returns all elements in this Cache ordered by entry creation time.

getAllKeysOrdered

public java.util.Iterator getAllKeysOrdered(boolean pLatestFirst)

Returns all elements in this Cache ordered by entry creation time.

main

public static void main(java.lang.String[] args)
                 throws java.lang.InterruptedException

Throws:

java.lang.InterruptedException