org.jasig.portal.concurrency.caching
Class ReferenceInvalidatingEntityCache

java.lang.Object
  extended by org.jasig.portal.concurrency.caching.ReferenceEntityCache
      extended by org.jasig.portal.concurrency.caching.ReferenceInvalidatingEntityCache
All Implemented Interfaces:
IEntityCache

public class ReferenceInvalidatingEntityCache
extends ReferenceEntityCache

Reference implementation of IEntityCache that is meant for a multi-server environment in which updates to cached entities may occur on peer caches on other JVMs, invalidating the local copy of the entity.

Cache entries are wrapped in a CacheEntry that records their creation time. At intervals, cleanupCache() is called by the cache's cleanup thread. When this happens, the class retrieves invalidation notices from its invalidation store and purges stale entries.

A fudge factor (clockTolerance) is employed to account for differences in system clocks among servers. This may cause a valid entry to be removed from the cache if it is newer than the corresponding invalidation by less than the fudge factor. However, this should not be to frequent, and assuming the factor is appropriately set, all relevant invalidations should occur.

Version:
$Revision: 1.14.4.2 $
Author:
Dan Ellentuck

Nested Class Summary
(package private)  class ReferenceInvalidatingEntityCache.CacheEntry
           
 
Nested classes/interfaces inherited from class org.jasig.portal.concurrency.caching.ReferenceEntityCache
ReferenceEntityCache.CacheSweeper
 
Field Summary
private static java.lang.String CACHE_ID_SEQUENCE
           
private  int cacheID
           
private  long clockTolerance
           
private static RDBMCachedEntityInvalidationStore invalidationStore
           
private  long lastUpdateMillis
           
 
Fields inherited from class org.jasig.portal.concurrency.caching.ReferenceEntityCache
cache, cleanupThread, entityType, log, simpleTypeName, sweepIntervalMillis, threadID
 
Constructor Summary
ReferenceInvalidatingEntityCache(java.lang.Class type, int maxSize, int maxUnusedTime, int sweepInterval)
          ReferenceInvalidatingEntityCache constructor comment.
ReferenceInvalidatingEntityCache(java.lang.Class type, int maxSize, int maxUnusedTime, int sweepInterval, int clock)
          ReferenceInvalidatingEntityCache constructor comment.
 
Method Summary
 void add(IBasicEntity entity)
          Wrap the incoming entity and add to the cache.
 void cleanupCache()
          Remove stale entries from the cache.
protected  void finalize()
          May want to do something with the invalidator thread.
 IBasicEntity get(java.lang.String key)
          Unwraps and returns the cached entity.
 int getCacheID()
           
private static RDBMCachedEntityInvalidationStore getInvalidationStore()
           
private  void initializeCacheID()
           
 void invalidate(IBasicEntity entity)
           
private  IBasicEntity primGet(java.lang.String key)
          Returns the WRAPPED cached entity.
private  void primRemove(java.lang.String key)
           
 void remove(java.lang.String key)
           
 void removeInvalidEntities()
          Retrieves invalidations that were added to the store by other caches since the last time we checked (fudged with the clockTolerance).
 java.lang.String toString()
          Returns a String that represents the value of this object.
 void update(IBasicEntity entity)
          First invalidate, then cache the incoming entity.
 
Methods inherited from class org.jasig.portal.concurrency.caching.ReferenceEntityCache
clearCache, debug, getCache, getEntityType, setCache, size
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

invalidationStore

private static RDBMCachedEntityInvalidationStore invalidationStore

lastUpdateMillis

private long lastUpdateMillis

clockTolerance

private long clockTolerance

cacheID

private int cacheID

CACHE_ID_SEQUENCE

private static final java.lang.String CACHE_ID_SEQUENCE
See Also:
Constant Field Values
Constructor Detail

ReferenceInvalidatingEntityCache

public ReferenceInvalidatingEntityCache(java.lang.Class type,
                                        int maxSize,
                                        int maxUnusedTime,
                                        int sweepInterval,
                                        int clock)
                                 throws CachingException
ReferenceInvalidatingEntityCache constructor comment.

Throws:
CachingException

ReferenceInvalidatingEntityCache

public ReferenceInvalidatingEntityCache(java.lang.Class type,
                                        int maxSize,
                                        int maxUnusedTime,
                                        int sweepInterval)
                                 throws CachingException
ReferenceInvalidatingEntityCache constructor comment.

Throws:
CachingException
Method Detail

add

public void add(IBasicEntity entity)
         throws CachingException
Wrap the incoming entity and add to the cache.

Specified by:
add in interface IEntityCache
Overrides:
add in class ReferenceEntityCache
Parameters:
entity - the entity to be added to the cache.
Throws:
CachingException

cleanupCache

public void cleanupCache()
Remove stale entries from the cache.

Specified by:
cleanupCache in interface IEntityCache
Overrides:
cleanupCache in class ReferenceEntityCache

finalize

protected void finalize()
                 throws java.lang.Throwable
May want to do something with the invalidator thread.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable

get

public IBasicEntity get(java.lang.String key)
Unwraps and returns the cached entity.

Specified by:
get in interface IEntityCache
Overrides:
get in class ReferenceEntityCache
Parameters:
key - - the key of the entity.
Returns:
org.jasig.portal.IBasicEntity

getInvalidationStore

private static RDBMCachedEntityInvalidationStore getInvalidationStore()
                                                               throws CachingException
Returns:
org.jasig.portal.concurrency.caching.RDBMCachedEntityInvalidationStore
Throws:
CachingException

invalidate

public void invalidate(IBasicEntity entity)
                throws CachingException
Parameters:
entity - org.jasig.portal.IBasicEntity
Throws:
CachingException

primGet

private IBasicEntity primGet(java.lang.String key)
Returns the WRAPPED cached entity.

Parameters:
key - - the key of the entity.
Returns:
org.jasig.portal.IBasicEntity

primRemove

private void primRemove(java.lang.String key)
                 throws CachingException
Parameters:
key - the entity to be un-cached.
Throws:
CachingException

remove

public void remove(java.lang.String key)
            throws CachingException
Specified by:
remove in interface IEntityCache
Overrides:
remove in class ReferenceEntityCache
Parameters:
key - - the key of the entity to be un-cached.
Throws:
CachingException

removeInvalidEntities

public void removeInvalidEntities()
Retrieves invalidations that were added to the store by other caches since the last time we checked (fudged with the clockTolerance). If a cache entry exists for the invalidation, and the entry is older than the invalidation (again, fudged with the clockTolerance), then the entry is removed. This may drop a few perfectly valid entries from the cache that are newer than the corresponding invalidation by less than the fudge factor. However, assuming the factor is appropriately set, all relevant invalidations should occur.


toString

public java.lang.String toString()
Returns a String that represents the value of this object.

Overrides:
toString in class ReferenceEntityCache
Returns:
a string representation of the receiver

update

public void update(IBasicEntity entity)
            throws CachingException
First invalidate, then cache the incoming entity.

Specified by:
update in interface IEntityCache
Overrides:
update in class ReferenceEntityCache
Parameters:
entity - the entity to be updated in the cache.
Throws:
CachingException

getCacheID

public int getCacheID()
Returns:
int

initializeCacheID

private void initializeCacheID()
                        throws CachingException
Throws:
CachingException