CoreCache (IBM WebSphere Application Server, Release 9.0)

```
public interface CoreCache
```
This class is the underlying cache interface for a cache provider, and contains the methods used to get, put, inspect and manage the current state of the cache. Methods of the CoreCache are called for caching of servlets, JSPs, webservices, WebSphere Commands and POJOs in DistributedMap and DistributedNioMap. In relation to Dynacache, each instance of the CoreCache interface represents a cache instance.
Implementation Details
- If the implementor of the CoreCache intends to return a copy (not just a reference) of the CacheEntry when a CacheEntry 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 the put(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

Methods
Modifier and Type	Method and Description
`void`	`clear()` This method clears everything from the cache, so that it returns to the state it was in when it was instantiated.
`boolean`	`containsCacheId(java.lang.Object cacheId)` Returns true if memory cache contains a mapping for the specified cache ID.
`CacheEntry`	`get(java.lang.Object cacheId)` Returns the CacheEntry identified by the specified cache ID.
`java.util.Set<java.lang.Object>`	`getCacheIds()` Returns a set view of the cache IDs contained in the memory cache.
`java.util.Set<java.lang.Object>`	`getCacheIds(java.lang.Object keyword)` Returns the cache IDs that are associated with a dependency ID.
`java.lang.String`	`getCacheName()` Returns the name of the cache instance
`com.ibm.wsspi.cache.CacheStatistics`	`getCacheStatistics()` Returns various cache statistics encapsulated int the CacheStatistics interface.
`java.util.Set<java.lang.Object>`	`getDependencyIds()` Returns the dependency IDs for all the cache entries.
`java.util.Set<java.lang.Object>`	`getTemplateIds()` Returns the Template IDs for all the cache entries.
`void`	`invalidate(java.lang.Object id, boolean waitOnInyvalidation)` Invalidates all the cache entries dependent on the specified cache ID.
`void`	`invalidateByCacheId(java.lang.Object cacheId, boolean waitOnInvalidation)` Invalidates the cache id.
`void`	`invalidateByDependency(java.lang.Object dependency, boolean waitOnInvalidation)` Invalidates all the cache entries dependent on the specified dependency ID.
`void`	`invalidateByTemplate(java.lang.String template, boolean waitOnInvalidation)` Invalidates all the cache entries dependent on the specified template ID.
`CacheEntry`	`put(EntryInfo ei, java.lang.Object value)` Puts an entry into the CoreCache.
`void`	`refreshEntry(java.lang.Object CacheId)` Refresh the entry by updating the LRU location.
`void`	`setEventSource(com.ibm.wsspi.cache.EventSource eventSource)`
`void`	`start()` This method will be invoked once Dynacache is ready to use the `CoreCache`.
`void`	`stop()` This method will be invoked when the application server is stopped.
`void`	`touch(java.lang.Object id, long validatorExpirationTime, long expirationTime)` The touch method updates the expiration times and the state of an entry in the CoreCache.

- Method Detail
  - 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
```
boolean containsCacheId(java.lang.Object cacheId)
```
    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
```
CacheEntry get(java.lang.Object cacheId)
```
    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 the CacheEntry 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 be null.
    
    Returns:
    The entry identified by the cache ID. null if the cache ID is not found in the cache.
  - getCacheIds
```
java.util.Set<java.lang.Object> 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
```
java.util.Set<java.lang.Object> getCacheIds(java.lang.Object keyword)
```
    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
```
com.ibm.wsspi.cache.CacheStatistics getCacheStatistics()
```
    Returns various cache statistics encapsulated int the CacheStatistics interface.
    
    Returns:
    CacheStatistics
  - getDependencyIds
```
java.util.Set<java.lang.Object> 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
```
java.util.Set<java.lang.Object> 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
```
void invalidate(java.lang.Object id,
              boolean waitOnInyvalidation)
```
    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
```
void invalidateByCacheId(java.lang.Object cacheId,
                       boolean waitOnInvalidation)
```
    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
```
void invalidateByDependency(java.lang.Object dependency,
                          boolean waitOnInvalidation)
```
    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
```
void invalidateByTemplate(java.lang.String template,
                        boolean waitOnInvalidation)
```
    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
```
CacheEntry put(EntryInfo ei,
             java.lang.Object value)
```
    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 the EntryInfo. The CacheProvider should use the getters provided on the EntryInfo 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
```
void refreshEntry(java.lang.Object CacheId)
```
    Refresh the entry by updating the LRU location.
    
    Parameters:
    cacheId -
  - setEventSource
```
void setEventSource(com.ibm.wsspi.cache.EventSource eventSource)
```
  - start
```
void start()
```
    This method will be invoked once Dynacache is ready to use the CoreCache. It is the responsibility of the CacheProvider to initialize the internal state of this cache instance in the CacheProvider.createCache(CacheConfig cc) method
  - stop
```
void stop()
```
    This method will be invoked when the application server is stopped. At this point the CacheProvider ought to cleanup any resources related to the this cache instance
  - touch
```
void touch(java.lang.Object id,
         long validatorExpirationTime,
         long expirationTime)
```
    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 the CacheEntry.
    Parameters:
    id - The cache ID for the cache value to be found. It cannot be null.
    validatorExpirationTime - The value of validator expiration time
    expirationTime - The value of expiration time
  - getCacheName
```
java.lang.String getCacheName()
```
    Returns the name of the cache instance
    
    Returns:
    name of a cache instance that is unique within this JVM.

clear

containsCacheId

get

getCacheIds

getCacheIds

getCacheStatistics

getDependencyIds

getTemplateIds

invalidate

invalidateByCacheId

invalidateByDependency

invalidateByTemplate

put

refreshEntry

setEventSource

start

stop

touch

getCacheName