atg.service.cache

Class Cache

java.lang.Object

atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

atg.nucleus.GenericService

atg.service.cache.AbstractCache

atg.service.cache.Cache

All Implemented Interfaces:

atg.core.logging.Logging, atg.core.logging.TraceLogging, 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 AbstractCache
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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
Cache() Constructor

Method Summary

Methods

Modifier and Type	Method and Description
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.
java.lang.Object	get(java.lang.Object pKey, boolean pCreate) Searches the cache for the object with the specified key.
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.
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	getNumCacheEntries() Returns the number of entries currently in the cache
int	getNumKeyParts() The number of key parts this cache expects.
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).
java.util.Iterator	getValidKeysOrdered(boolean pLatestFirst) Returns all elements in this Cache ordered by entry creation time.
protected boolean	hasExpiredValue(atg.service.cache.Cache.Entry pEntry) Return whether the specified entry has expired.
protected boolean	hasOtherwiseExpired(java.lang.Object pKey, java.lang.Object pValue) Provide an extension point for adding additional expiration logic.
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	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	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.service.cache.AbstractCache

getCacheAdapter, getCacheRemovalListener, getMaximumCacheEntries, getMaximumCacheSize, getMaximumEntryLifetime, getMaximumEntrySize, getSize, getUsedMemoryCapacity, isCaching, setCacheAdapter, setCacheRemovalListener, setMaximumCacheEntries, setMaximumCacheSize, setMaximumEntryLifetime, setMaximumEntrySize

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)

Description copied from class: AbstractCache

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

Specified by:

contains in class AbstractCache

Parameters:

pKey - the key to check for in our cache

Returns:

true if all the key was found in the cache.

contains

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

Description copied from class: AbstractCache

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

Overrides:

contains in class AbstractCache

Parameters:

pKeys - the keys to check for in our cache.

Returns:

true if all the keys were found 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.

Specified by:

get in class AbstractCache

Parameters:

pKey - the key whose value should be returned.

Returns:

the value associated with pKey, or null.

Throws:

java.lang.Exception - on an error (such an error occurring when a CacheAdapter fetches a missing value).

get

public java.lang.Object get(java.lang.Object pKey,
                   boolean pCreate)
                     throws java.lang.Exception

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

Specified by:

get in class AbstractCache

Parameters:

pKey - the key of the value to fetch

pCreate - whether to create a missing value.

Returns:

the value associated with pKey

Throws:

java.lang.Exception - on an error (such an error occurring when a CacheAdapter fetches a missing value).

hasExpiredValue

protected boolean hasExpiredValue(atg.service.cache.Cache.Entry pEntry)

Return whether the specified entry has expired.

hasOtherwiseExpired

protected boolean hasOtherwiseExpired(java.lang.Object pKey,
                          java.lang.Object pValue)

Provide an extension point for adding additional expiration logic.

Overrides:

hasOtherwiseExpired in class AbstractCache

Parameters:

pKey - the key of the possibly expired cache entry

pValue - pValue the value of possibly expired cache entry

Returns:

true if has expired, false otherwise.

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.

Specified by:

get in class AbstractCache

Parameters:

pKeys - the keys whose values should be returned.

Returns:

the values associated with pKeys

Throws:

java.lang.Exception - on an error (such an error occurring when a CacheAdapter fetches a missing value).

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.

Overrides:

isExpiredValueStillGood in class AbstractCache

Parameters:

pKey - the key the corresponds to the value

pValue - the value to check

Returns:

true if the value is still good, false otherwise.

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.

Specified by:

put in class AbstractCache

Parameters:

pKey - the key to put in the cache.

pValue - the value to put in the cache associated with pKey.

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.)

Specified by:

remove in class AbstractCache

Parameters:

pKey - the key of the entry to remove.

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.

Specified by:

flush in class AbstractCache

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

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.

getNumCacheEntries

public int getNumCacheEntries()

Returns the number of entries currently in the cache

Specified by:

getNumCacheEntries in class AbstractCache

Returns:

the number of entries

getUsedCapacity

public double getUsedCapacity()

Returns the ratio of cache entries to maximum cache entries.

Overrides:

getUsedCapacity in class AbstractCache

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).

Specified by:

getUsedMemory in class AbstractCache

Returns:

the amount of memory taken up by the entries in the cache

getAccessCount

public int getAccessCount()

Returns the total number of accesses

Specified by:

getAccessCount in class AbstractCache

Returns:

the total number of accesses (hits plus misses)

getHitCount

public int getHitCount()

Returns the number of cache hits

Specified by:

getHitCount in class AbstractCache

Returns:

the total number of hits

getHitRatio

public double getHitRatio()

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

Overrides:

getHitRatio in class AbstractCache

Returns:

the hit ratio

getTimeoutCount

public int getTimeoutCount()

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

Specified by:

getTimeoutCount in class AbstractCache

Returns:

the number of invalidations

getAllElements

public java.util.Iterator getAllElements()

Returns all elements in this Cache.

Specified by:

getAllElements in class AbstractCache

Returns:

an interator of all the elements

getAllKeys

public java.util.Iterator getAllKeys()

Returns all elements in this Cache.

Specified by:

getAllKeys in class AbstractCache

Returns:

an interator of all the keys

getValidKeysOrdered

public java.util.Iterator getValidKeysOrdered(boolean pLatestFirst)

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

Specified by:

getValidKeysOrdered in class AbstractCache

Parameters:

pLatestFirst - whether to return the latest first.

Returns:

the value keys

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