atg.service.cache

Class AbstractCache<K,V>

java.lang.Object

atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

atg.nucleus.GenericService

atg.service.cache.AbstractCache<K,V>

Type Parameters:

K - the type of the keys of the cache

V - the type of the values of the 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.util.EventListener

Direct Known Subclasses:

Cache

public abstract class AbstractCache<K,V>
extends GenericService

An abstract parent to both Cache and ConcurrentCache.

Created: August 21 2013

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLASS_VERSION Class version string

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
AbstractCache()

Method Summary

Modifier and Type	Method and Description
abstract 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.
abstract void	flush() Flushes all entries from the cache, leaving it empty.
abstract V	get(java.lang.Object pKey) Searches the cache for the object with the specified key.
abstract java.lang.Object[]	get(java.lang.Object[] pKeys) Searches the cache for the objects with the specified keys.
abstract V	get(java.lang.Object pKey, boolean pCreate) Searches the cache for the object with the specified key.
abstract int	getAccessCount() Returns the total number of accesses
abstract java.util.Iterator<V>	getAllElements() Returns all elements in this Cache.
abstract java.util.Iterator<K>	getAllKeys() Returns all elements in this Cache.
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.
abstract 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.
abstract 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
abstract int	getSubKeysInvalidationTargetCounts() The count of subkey invalidation targets.
abstract 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.
abstract 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
abstract java.util.Iterator<K>	getValidKeysOrdered(boolean pLatestFirst) Returns all elements in this Cache ordered by entry creation time.
protected boolean	hasOtherwiseExpired(K pKey, V pValue) Provide an extension point for adding additional expiration logic.
boolean	isCaching() Whether we are actively caching at all.
protected boolean	isExpiredValueStillGood(K pKey, V pValue) Return whether the expired value is still good.
abstract void	put(K pKey, V pValue) Put the value pValue in the cache and associate it with pKey.
abstract boolean	remove(java.lang.Object pKey) Invalidates the entry with the given key.
abstract 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.

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 java.lang.String CLASS_VERSION

Class version string

Constructor Detail

AbstractCache

public AbstractCache()

Method Detail

getCacheAdapter

public CacheAdapter getCacheAdapter()

The Adapter used to create entries in the cache

Returns:

setCacheAdapter

public void setCacheAdapter(CacheAdapter pAdapter)

The Adapter used to create entries in the cache

Parameters:

pAdapter - the adapter to set.

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

isCaching

public boolean isCaching()

Whether we are actively caching at all.

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.

contains

public abstract boolean contains(java.lang.Object pKey)

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

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)

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

Parameters:

pKeys - the keys to check for in our cache.

Returns:

true if all the keys were found in the cache.

get

public abstract V 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.

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 abstract V 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.

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

get

public abstract 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.

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(K pKey,
                                          V 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

Returns:

true if the value is still good, false otherwise.

hasOtherwiseExpired

protected boolean hasOtherwiseExpired(K pKey,
                                      V pValue)

Provide an extension point for adding additional expiration logic.

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.

put

public abstract void put(K pKey,
                         V pValue)

Put the value pValue in the cache and associate it with pKey.

Parameters:

pKey - the key to put in the cache.

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

remove

public abstract boolean remove(java.lang.Object pKey)

Invalidates the entry with the given key.

Parameters:

pKey - the key of the entry to remove.

Returns:

true if the item was found and removed

flush

public abstract void flush()

Flushes all entries from the cache, leaving it empty.

getSize

public int getSize()

Returns the number of entries currently in the cache

Returns:

the number of entries

getNumCacheEntries

public abstract int getNumCacheEntries()

Returns the number of entries currently in the cache

Returns:

the number of entries

getUsedCapacity

public double getUsedCapacity()

Returns the ratio of cache entries to maximum cache entries.

Returns:

the ratio of cache entries to maximum cache entries.

getUsedMemory

public abstract int getUsedMemory()

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

Returns:

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

getAccessCount

public abstract int getAccessCount()

Returns the total number of accesses

Returns:

the total number of accesses (hits plus misses)

getHitCount

public abstract int getHitCount()

Returns the number of cache hits

Returns:

the total number of hits

getHitRatio

public double getHitRatio()

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

Returns:

the hit ratio

getTimeoutCount

public abstract int getTimeoutCount()

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

Returns:

the number of invalidations

getAllElements

public abstract java.util.Iterator<V> getAllElements()

Returns all elements in this Cache.

Returns:

an interator of all the elements

getAllKeys

public abstract java.util.Iterator<K> getAllKeys()

Returns all elements in this Cache.

Returns:

an interator of all the keys

getUsedMemoryCapacity

public double getUsedMemoryCapacity()

Returns the ratio of memory size to maximum memory size

Returns:

the ratio of memory size to maximum memory size

getValidKeysOrdered

public abstract java.util.Iterator<K> getValidKeysOrdered(boolean pLatestFirst)

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

Parameters:

pLatestFirst - whether to return the latest first.

Returns:

the value keys

removeByPartialKey

public abstract 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

getSubKeysInvalidationTargetCounts

public abstract int getSubKeysInvalidationTargetCounts()

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

Returns:

a count of the sub key invalidation targets.