Package com.ibm.wsspi.cache

Interface CoreCache

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

    Modifier and Type
    Method
    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(Object cacheId)
    Returns true if memory cache contains a mapping for the specified cache ID.
    CacheEntry
    get(Object cacheId)
    Returns the CacheEntry identified by the specified cache ID.
    Set<Object>
    getCacheIds()
    Returns a set view of the cache IDs contained in the memory cache.
    Set<Object>
    getCacheIds(Object keyword)
    Returns the cache IDs that are associated with a dependency ID.
    String
    getCacheName()
    Returns the name of the cache instance
    CacheStatistics
    getCacheStatistics()
    Returns various cache statistics encapsulated int the CacheStatistics interface.
    Set<Object>
    getDependencyIds()
    Returns the dependency IDs for all the cache entries.
    Set<Object>
    getTemplateIds()
    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.
    CacheEntry
    put(EntryInfo ei, Object value)
    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 the CoreCache.
    void
    stop()
    This method will be invoked when the application server is stopped.
    void
    touch(Object id, long validatorExpirationTime, long expirationTime)
    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

      boolean containsCacheId(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(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

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

      Set<Object> getCacheIds(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

      CacheStatistics getCacheStatistics()
      Returns various cache statistics encapsulated int the CacheStatistics interface.
      Returns:
      CacheStatistics

    • getDependencyIds

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

      Set<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(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(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(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(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, 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(Object CacheId)
      Refresh the entry by updating the LRU location.
      Parameters:
      cacheId -

    • setEventSource

      void setEventSource(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(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

      String getCacheName()
      Returns the name of the cache instance
      Returns:
      name of a cache instance that is unique within this JVM.