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

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() It will dump the cache information as string.
void	dump(java.io.PrintStream aStream) This method is meant to help in debugging.
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.
long	getCacheEntryTime(java.lang.Object key) Get the creation time of an object in cache.
int	getHitCount() Returns the number of cache hits
double	getHitRatio() Returns the number of cache hits / total number of cache accesses
int	getNumCacheEntries() Returns the number of entries currently in the cache
int	getSubKeysInvalidationTargetCounts() The count of subkey invalidation targets.
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 pKey, 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.
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, getEnablePartialKeyInvalidation, getKeyPartsForInvalidation, getMaximumCacheEntries, getMaximumCacheSize, getMaximumEntryLifetime, getMaximumEntrySize, getNumKeyParts, getSize, getUsedMemoryCapacity, isCaching, setCacheAdapter, setCacheRemovalListener, setEnablePartialKeyInvalidation, setKeyPartsForInvalidation, setMaximumCacheEntries, setMaximumCacheSize, setMaximumEntryLifetime, setMaximumEntrySize, setNumKeyParts

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, toString

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, 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

getSubKeysInvalidationTargetCounts

public int getSubKeysInvalidationTargetCounts()

Description copied from class: AbstractCache

The count of subkey invalidation targets. This is the count of targets across all subkeys. This method is provided for debugging (and to make sure those targets are getting cleaned up properly).

Specified by:

getSubKeysInvalidationTargetCounts in class AbstractCache

Returns:

a count of the sub key invalidation targets.

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)

This method is meant to help in debugging. It will print the current key/value/creation time. A PrintStream needs to be supplied for example System.out

dump

public java.lang.String dump()

It will dump the cache information as string. The output will be a stream of keys, values & creation times delimited by carriage returns ('\n').

Returns:

the string

getCacheEntryTime

public long getCacheEntryTime(java.lang.Object key)

Get the creation time of an object in cache. If not found, then it returns -1

Parameters:

key - the key of the value to fetch

Returns:

the time of object when it is created in cache

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 pKey,
                                          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.

Specified by:

removeByPartialKey in class AbstractCache

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

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