Interface CoreCache
Implementation Details
- If the implementor of the CoreCache intends to return a copy (not just a reference) of the
CacheEntry
when aCacheEntry get(Object cacheId)
is issued, then the provider does NOT need to follow the implementation guidelines for reference counting specified in the javadoc of this class's methods. A CacheEntry is created by the provider using the cache ID and value passed into theput(EntryInfo ei, Object value);
method. - The Dynacache code that calls the CoreCache does NOT synchronize on ANY of the methods of the CoreCache. The cache provider's implementation of the CoreCache is expected to apply the cache provider's locking policies on the operations of the CoreCache.
- Since:
- WAS 6.1.0.27
-
Method Summary
Modifier and TypeMethodDescriptionvoid
clear()
This method clears everything from the cache, so that it returns to the state it was in when it was instantiated.boolean
containsCacheId
(Object cacheId) Returns true if memory cache contains a mapping for the specified cache ID.Returns the CacheEntry identified by the specified cache ID.Returns a set view of the cache IDs contained in the memory cache.getCacheIds
(Object keyword) Returns the cache IDs that are associated with a dependency ID.Returns the name of the cache instanceReturns various cache statistics encapsulated int the CacheStatistics interface.Returns the dependency IDs for all the cache entries.Returns the Template IDs for all the cache entries.void
invalidate
(Object id, boolean waitOnInyvalidation) Invalidates all the cache entries dependent on the specified cache ID.void
invalidateByCacheId
(Object cacheId, boolean waitOnInvalidation) Invalidates the cache id.void
invalidateByDependency
(Object dependency, boolean waitOnInvalidation) Invalidates all the cache entries dependent on the specified dependency ID.void
invalidateByTemplate
(String template, boolean waitOnInvalidation) Invalidates all the cache entries dependent on the specified template ID.Puts an entry into the CoreCache.void
refreshEntry
(Object CacheId) Refresh the entry by updating the LRU location.void
setEventSource
(EventSource eventSource) void
start()
This method will be invoked once Dynacache is ready to use theCoreCache
.void
stop()
This method will be invoked when the application server is stopped.void
The touch method updates the expiration times and the state of an entry in the CoreCache.
-
Method Details
-
clear
void clear()This method clears everything from the cache, so that it returns to the state it was in when it was instantiated. -
containsCacheId
Returns true if memory cache contains a mapping for the specified cache ID.- Parameters:
cacheId
- cache ID is to be tested.- Returns:
true
- memory cache contains the specified cacheID.
-
get
Returns the CacheEntry identified by the specified cache ID. A CacheEntry holds the cache ID(i.e. the key), value and the metadata for a cached item.Implementation Guidelines: On a
get
the implementation of theCacheEntry
should pin the entry in the Cache. The internal reference count of the CacheEntry should be incremented.CacheEntry.incrementReferenceCount();
- Parameters:
cacheId
- The cache ID object for the entry to be found. It cannot benull
.- Returns:
- The entry identified by the cache ID.
null
if the cache ID is not found in the cache.
-
getCacheIds
Returns a set view of the cache IDs contained in the memory cache.- Returns:
- A
Set
of cache IDs or empty set if there is no cache ID.
-
getCacheIds
Returns the cache IDs that are associated with a dependency ID. It returns an empty set if no cache ID is associated with it.
Dependency elements are used to group related cache items. Cache entries having the same depenendency ID are managed as a group. Each related cache item shares the same dependency id, so it only takes one member of the dependency group to get invalidated, for the rest of the group to be evicted. The dependency ID can be as simple as just a name such as storeId- Parameters:
keyword
- dependency ID or template ID for the groupof cache IDs.- Returns:
- A
Set
of cache IDs or empty set if no cache ID is associated with it.
-
getCacheStatistics
CacheStatistics getCacheStatistics()Returns various cache statistics encapsulated int the CacheStatistics interface.- Returns:
CacheStatistics
-
getDependencyIds
Returns the dependency IDs for all the cache entries. A dependency provides a mechanism for grouping of cache-ids. A dependency-id can also be a cache-id. Dependency IDs label cache entries and are used by invalidation rules to invalidate & timeout one or more cache entries at a time. The relationship beween a dependency-id and its dependent ids is formed via invalidation rules in the cachespec.xml for servlet caches. For object caches this relationship is explicitly specified via the DistributedMap APIs.- Returns:
- A set of dependency IDs.
-
getTemplateIds
Returns the Template IDs for all the cache entries. A template provides a mechanism for grouping of servlet and JSP cache-ids. A template is semantically equivalent to a dependency. However a template is a mechanism of grouping for servlet, JSP and portal cache objects. A template for instance can be the URI or the context root of an application or URI of a top level servlet.- Returns:
- A set of template IDs.
-
invalidate
Invalidates all the cache entries dependent on the specified cache ID. If the ID is for a specific cache entry, then only that object is invalidated. If the ID is for a dependency id, then all objects that share that dependency ID will be invalidated.Implementation Guidelines: This method unpins an entry from the cache if the internal reference count is zero. If the CacheEntry is being used by other clients i.e. its reference count is greater than zero, this cache entry is marked for removal.
CacheEntry oldCacheEntry = cacheMap.remove(id); if oldCacheEntry.getReferenceCount() > 0 then oldCacheEntry.setRemoveWhenUnpinned(); if oldCacheEntry.getReferenceCount() == 0 then if oldCacheEntry.isPooled() oldCacheEntry.returnToPool (pooling of CacheEntry) else oldCacheEntry = null (NO pooling of CacheEntry, explicit release for garbage collection)
- Parameters:
id
- The cache ID or dependency ID. It cannot be null.waitOnInvalidation
-true
indicates that this method should not return until the invalidations have taken effect on all caches.false
indicates that the invalidations will be queued for later batch processing.
-
invalidateByCacheId
Invalidates the cache id.Implementation Guidelines: This method unpins an entry from the cache if the internal reference count is zero. If the CacheEntry is being used by other clients i.e. its reference count is greater than zero, this cache entry is marked for removal.
CacheEntry oldCacheEntry = cacheMap.remove(id); if oldCacheEntry.getReferenceCount() > 0 then oldCacheEntry.setRemoveWhenUnpinned(); if oldCacheEntry.getReferenceCount() == 0 then if oldCacheEntry.isPooled() oldCacheEntry.returnToPool (pooling of CacheEntry) else oldCacheEntry = null (NO pooling of CacheEntry, explicit release for garbage collection)
- Parameters:
cacheId
- The cache ID. It cannot be null.waitOnInvalidation
-true
indicates that this method should not return until the invalidations have taken effect on all caches.false
indicates that the invalidations will be queued for later batch processing.
-
invalidateByDependency
Invalidates all the cache entries dependent on the specified dependency ID.Implementation Guidelines: This method unpins an entry from the cache if the internal reference count is zero. If the CacheEntry is being used by other clients i.e. its reference count is greater than zero, this cache entry is marked for removal.
CacheEntry oldCacheEntry = cacheMap.remove(id); if oldCacheEntry.getReferenceCount() > 0 then oldCacheEntry.setRemoveWhenUnpinned(); if oldCacheEntry.getReferenceCount() == 0 then if oldCacheEntry.isPooled() oldCacheEntry.returnToPool (pooling of CacheEntry) else oldCacheEntry = null (NO pooling of CacheEntry, explicit release for garbage collection)
- Parameters:
dependency
- The dependency ID. It cannot be null.waitOnInvalidation
-true
indicates that this method should not return until the invalidations have taken effect on all caches.false
indicates that the invalidations will be queued for later batch processing.
-
invalidateByTemplate
Invalidates all the cache entries dependent on the specified template ID.Implementation Guidelines: This method unpins an entry from the cache if the internal reference count is zero. If the CacheEntry is being used by other clients i.e. its reference count is greater than zero, this cache entry is marked for removal.
CacheEntry oldCacheEntry = cacheMap.remove(id); if oldCacheEntry.getReferenceCount() > 0 then oldCacheEntry.setRemoveWhenUnpinned(); if oldCacheEntry.getReferenceCount() == 0 then if oldCacheEntry.isPooled() oldCacheEntry.returnToPool (pooling of CacheEntry) else oldCacheEntry = null (NO pooling of CacheEntry, explicit release for garbage collection)
- Parameters:
template
- The template ID. It cannot be null.waitOnInvalidation
-true
indicates that this method should not return until the invalidations have taken effect on all caches.false
indicates that the invalidations will be queued for later batch processing.
-
put
Puts an entry into the CoreCache. If the entry already exists in the cache, this method will ALSO update the same.Implementation Guidelines: Cache providers should store a {cacheId --> CacheEntry} association in their cache. A
CacheEntry
is a container object containing the cache key, value and metadata for a particular cached item. The CacheEntry object is owned by the CacheProvider.
This method unpins an entry from the cache if the internal reference count is zero. If the CacheEntry is being used by other clients i.e. its reference count is greater than zero, this cache entry is marked for removal.
CacheEntry oldCacheEntry = cacheMap.put(id);
if the Old CacheEntry.getReferenceCount() > 0, oldCacheEntry.setRemoveWhenUnpinned()
if the old CacheEntry.getReferenceCount() == 0, oldCacheEntry.returnToPool() or oldCacheEntry = null
The CacheProvider has to create associations between this entry and the rest of the entries in the cache using the getDataIds() and getTemplates() methods on theEntryInfo
. The CacheProvider should use the getters provided on theEntryInfo
to control and set the expiration timeout and other characteristics of the cached item in its own cache.- Parameters:
ei
- The metadata of the cache entry including its key.value
- The object to store in the cache.- Returns:
- oldCacheEntry
The previous CacheEntry if any, associated with the key(ei) in the cache. If no key (ei) is found,
null
is returned.
-
refreshEntry
Refresh the entry by updating the LRU location.- Parameters:
cacheId
-
-
setEventSource
-
start
void start()This method will be invoked once Dynacache is ready to use theCoreCache
. It is the responsibility of theCacheProvider
to initialize the internal state of this cache instance in theCacheProvider.createCache(CacheConfig cc)
method -
stop
void stop()This method will be invoked when the application server is stopped. At this point theCacheProvider
ought to cleanup any resources related to the this cache instance -
touch
The touch method updates the expiration times and the state of an entry in the CoreCache.Implementation Guidelines: A
CacheEntry
has three possible states:- Expired = cached content not needed and not available anymore
- Invalid = cached content currently invalid but still available
- Valid = cached content valid and available
After the validatorExpirationTime has passed a CacheEntry transitions from the Valid to the Invalid state. After the expirationTime has passed a CacheEntry transitions from the Invalid to the Expired state. An expired CacheEntry is eventually purged from the cache.
The validatorExpirationTime for a CacheEntry is always less than or equal to the expirationTime. The validatorExpirationTime and expirationTime control the state of theCacheEntry
.- Parameters:
id
- The cache ID for the cache value to be found. It cannot be null.validatorExpirationTime
- The value of validator expiration timeexpirationTime
- The value of expiration time
-
getCacheName
String getCacheName()Returns the name of the cache instance- Returns:
- name of a cache instance that is unique within this JVM.
-