org.sakaiproject.component.framework.memory
Class MemCache

java.lang.Object
  extended byorg.sakaiproject.component.framework.memory.MemCache
All Implemented Interfaces:
Cache, Cacher, Observer, Runnable
Direct Known Subclasses:
HardCache, MultiRefCacheImpl, SiteCacheImpl

public class MemCache
extends Object
implements Cache, Runnable, Observer

A Cache of objects with keys with a limited lifespan.

When the object expires, the cache calls upon a CacheRefresher to update the key's value. The update is done in a separate thread.

Version:
$Revision: 1461 $
Author:
University of Michigan, Sakai Software Development Team

Nested Class Summary
protected  class MemCache.CacheEntry
          The cache entry.
 
Field Summary
protected  boolean m_complete
          If true, we have all the entries that there are in the cache.
protected  boolean m_disabled
          If true, we are disabled.
protected  EventTrackingService m_eventTrackingService
          Constructor injected event tracking service.
protected  long m_getCount
          Count of access requests.
protected  List m_heldEvents
          The events we are holding for later processing.
protected  long m_hitCount
          Count of access requests satisfied with a cached entry.
protected  boolean m_holdEventProcessing
          If true, we are going to hold any events we see in the m_heldEvents list for later processing.
protected  Logger m_logger
          Constructor injected logger service.
protected  Map m_map
          Map holding cached entries.
protected  BasicMemoryService m_memoryService
          Constructor injected memory service.
protected  Set m_partiallyComplete
          Alternate isComplete, based on patterns.
protected  long m_putCount
          Count of things put into the cache.
protected  CacheRefresher m_refresher
          The object that will deal with expired entries.
protected  long m_refresherSleep
          The number of seconds to sleep between expiration checks.
protected  String m_resourcePattern
          The string that all resources in this cache will start with.
protected  boolean m_softRefs
          If true, we do soft references, else we do hard ones.
protected  Thread m_thread
          The thread which runs the expiration check.
protected  boolean m_threadStop
          My thread's quit flag.
 
Constructor Summary
MemCache(BasicMemoryService memoryService, EventTrackingService eventTrackingService, Logger logger)
          Construct the Cache.
MemCache(BasicMemoryService memoryService, EventTrackingService eventTrackingService, Logger logger, CacheRefresher refresher, long sleep)
          Construct the Cache.
MemCache(BasicMemoryService memoryService, EventTrackingService eventTrackingService, Logger logger, CacheRefresher refresher, String pattern)
          Construct the Cache.
MemCache(BasicMemoryService memoryService, EventTrackingService eventTrackingService, Logger logger, long sleep, String pattern)
          Construct the Cache.
 
Method Summary
 void clear()
          Clear all entries.
 boolean containsKey(Object key)
          Test for a non expired entry in the cache.
 boolean containsKeyExpiredOrNot(Object key)
          Test for an entry in the cache - expired or not.
protected  void continueUpdate(Event event)
          Complete the update, given an event that we know we need to act upon.
 void destroy()
          Clean up.
 void disable()
          Disable the cache.
 boolean disabled()
          Is the cache disabled?
 void enable()
          Enable the cache.
 void expire(Object key)
          Expire this object.
 Object get(Object key)
          Get the non expired entry, or null if not there (or expired)
 List getAll()
          Get all the non-expired non-null entries.
 List getAll(String path)
          Get all the non-expired non-null entries that are in the specified reference path.
 String getDescription()
          Return a description of the cacher.
 Object getExpiredOrNot(Object key)
          Get the entry, or null if not there (expired entries are returned, too).
 List getIds()
          Get all the keys, eache modified to remove the resourcePattern prefix.
 List getKeys()
          Get all the keys
 long getSize()
          Return the size of the cacher - indicating how much memory in use.
 void holdEvents()
          Set the cache to hold events for later processing to assure an atomic "complete" load.
 boolean isComplete()
          Are we complete?
 boolean isComplete(String path)
          Are we complete for one level of the reference hierarchy?
 void processEvents()
          Restore normal event processing in the cache, and process any held events now.
 void put(Object key, Object payload)
          Cache an object - don't automatically exipire it.
 void put(Object key, Object payload, int duration)
          Cache an object
protected  String referencePath(String ref)
          Compute the reference path (i.e. the container) for a given reference.
 void remove(Object key)
          Remove this entry from the cache.
 void resetCache()
          Clear out as much as possible anything cached; re-sync any cache that is needed to be kept.
 void run()
          Run the expiration thread.
 void setComplete()
          Set the cache to be complete, containing all possible entries.
 void setComplete(String path)
          Set the cache to be complete for one level of the reference hierarchy.
protected  void start()
          Start the expiration thread.
protected  void stop()
          Stop the expiration thread.
 void update(Observable o, Object arg)
          This method is called whenever the observed object is changed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

m_map

protected Map m_map
Map holding cached entries.


m_refresher

protected CacheRefresher m_refresher
The object that will deal with expired entries.


m_resourcePattern

protected String m_resourcePattern
The string that all resources in this cache will start with.


m_refresherSleep

protected long m_refresherSleep
The number of seconds to sleep between expiration checks.


m_disabled

protected boolean m_disabled
If true, we are disabled.


m_complete

protected boolean m_complete
If true, we have all the entries that there are in the cache.


m_partiallyComplete

protected Set m_partiallyComplete
Alternate isComplete, based on patterns.


m_holdEventProcessing

protected boolean m_holdEventProcessing
If true, we are going to hold any events we see in the m_heldEvents list for later processing.


m_heldEvents

protected List m_heldEvents
The events we are holding for later processing.


m_memoryService

protected BasicMemoryService m_memoryService
Constructor injected memory service.


m_eventTrackingService

protected EventTrackingService m_eventTrackingService
Constructor injected event tracking service.


m_logger

protected Logger m_logger
Constructor injected logger service.


m_softRefs

protected boolean m_softRefs
If true, we do soft references, else we do hard ones.


m_getCount

protected long m_getCount
Count of access requests.


m_hitCount

protected long m_hitCount
Count of access requests satisfied with a cached entry.


m_putCount

protected long m_putCount
Count of things put into the cache.


m_thread

protected Thread m_thread
The thread which runs the expiration check.


m_threadStop

protected boolean m_threadStop
My thread's quit flag.

Constructor Detail

MemCache

public MemCache(BasicMemoryService memoryService,
                EventTrackingService eventTrackingService,
                Logger logger)
Construct the Cache. No automatic refresh handling.


MemCache

public MemCache(BasicMemoryService memoryService,
                EventTrackingService eventTrackingService,
                Logger logger,
                CacheRefresher refresher,
                String pattern)
Construct the Cache. Attempts to keep complete on Event notification by calling the refresher.

Parameters:
refresher - The object that will handle refreshing of event notified modified or added entries.
pattern - The "startsWith()" string for all resources that may be in this cache - if null, don't watch events for updates.

MemCache

public MemCache(BasicMemoryService memoryService,
                EventTrackingService eventTrackingService,
                Logger logger,
                CacheRefresher refresher,
                long sleep)
Construct the Cache. Automatic refresh handling if refresher is not null.

Parameters:
refresher - The object that will handle refreshing of expired entries.
sleep - The number of seconds to sleep between expiration checks.

MemCache

public MemCache(BasicMemoryService memoryService,
                EventTrackingService eventTrackingService,
                Logger logger,
                long sleep,
                String pattern)
Construct the Cache. Event scanning if pattern not null - will expire entries.

Parameters:
sleep - The number of seconds to sleep between expiration checks.
pattern - The "startsWith()" string for all resources that may be in this cache - if null, don't watch events for expiration.
Method Detail

destroy

public void destroy()
Clean up.

Specified by:
destroy in interface Cache

put

public void put(Object key,
                Object payload,
                int duration)
Cache an object

Specified by:
put in interface Cache
Parameters:
key - The key with which to find the object.
payload - The object to cache.
duration - The time to cache the object (seconds).

put

public void put(Object key,
                Object payload)
Cache an object - don't automatically exipire it.

Specified by:
put in interface Cache
Parameters:
key - The key with which to find the object.
payload - The object to cache.

containsKeyExpiredOrNot

public boolean containsKeyExpiredOrNot(Object key)
Test for an entry in the cache - expired or not.

Specified by:
containsKeyExpiredOrNot in interface Cache
Parameters:
key - The cache key.
Returns:
true if the key maps to a cache entry, false if not.

containsKey

public boolean containsKey(Object key)
Test for a non expired entry in the cache.

Specified by:
containsKey in interface Cache
Parameters:
key - The cache key.
Returns:
true if the key maps to a non-expired cache entry, false if not.

expire

public void expire(Object key)
Expire this object.

Specified by:
expire in interface Cache
Parameters:
key - The cache key.

getExpiredOrNot

public Object getExpiredOrNot(Object key)
Get the entry, or null if not there (expired entries are returned, too).

Specified by:
getExpiredOrNot in interface Cache
Parameters:
key - The cache key.
Returns:
The payload, or null if the payload is null, the key is not found. (Note: use containsKey() to remove this ambiguity).

get

public Object get(Object key)
Get the non expired entry, or null if not there (or expired)

Specified by:
get in interface Cache
Parameters:
key - The cache key.
Returns:
The payload, or null if the payload is null, the key is not found, or the entry has expired (Note: use containsKey() to remove this ambiguity).

getAll

public List getAll()
Get all the non-expired non-null entries.

Specified by:
getAll in interface Cache
Returns:
all the non-expired non-null entries, or an empty list if none.

getAll

public List getAll(String path)
Get all the non-expired non-null entries that are in the specified reference path. Note: only works with String keys.

Specified by:
getAll in interface Cache
Parameters:
path - The reference path.
Returns:
all the non-expired non-null entries, or an empty list if none.

getKeys

public List getKeys()
Get all the keys

Specified by:
getKeys in interface Cache
Returns:
The List of key values (Object).

getIds

public List getIds()
Get all the keys, eache modified to remove the resourcePattern prefix. Note: only works with String keys.

Specified by:
getIds in interface Cache
Returns:
The List of keys converted from references to ids (String).

clear

public void clear()
Clear all entries.

Specified by:
clear in interface Cache

remove

public void remove(Object key)
Remove this entry from the cache.

Specified by:
remove in interface Cache
Parameters:
key - The cache key.

disable

public void disable()
Disable the cache.

Specified by:
disable in interface Cache

enable

public void enable()
Enable the cache.

Specified by:
enable in interface Cache

disabled

public boolean disabled()
Is the cache disabled?

Specified by:
disabled in interface Cache
Returns:
true if the cache is disabled, false if it is enabled.

isComplete

public boolean isComplete()
Are we complete?

Specified by:
isComplete in interface Cache
Returns:
true if we have all the possible entries cached, false if not.

setComplete

public void setComplete()
Set the cache to be complete, containing all possible entries.

Specified by:
setComplete in interface Cache

isComplete

public boolean isComplete(String path)
Are we complete for one level of the reference hierarchy?

Specified by:
isComplete in interface Cache
Parameters:
path - The reference to the completion level.
Returns:
true if we have all the possible entries cached, false if not.

setComplete

public void setComplete(String path)
Set the cache to be complete for one level of the reference hierarchy.

Specified by:
setComplete in interface Cache
Parameters:
path - The reference to the completion level.

holdEvents

public void holdEvents()
Set the cache to hold events for later processing to assure an atomic "complete" load.

Specified by:
holdEvents in interface Cache

processEvents

public void processEvents()
Restore normal event processing in the cache, and process any held events now.

Specified by:
processEvents in interface Cache

resetCache

public void resetCache()
Clear out as much as possible anything cached; re-sync any cache that is needed to be kept.

Specified by:
resetCache in interface Cacher

getSize

public long getSize()
Return the size of the cacher - indicating how much memory in use.

Specified by:
getSize in interface Cacher
Returns:
The size of the cacher.

getDescription

public String getDescription()
Return a description of the cacher.

Specified by:
getDescription in interface Cacher
Returns:
The cacher's description.

start

protected void start()
Start the expiration thread.


stop

protected void stop()
Stop the expiration thread.


run

public void run()
Run the expiration thread.

Specified by:
run in interface Runnable

update

public void update(Observable o,
                   Object arg)
This method is called whenever the observed object is changed. An application calls an Observable object's notifyObservers method to have all the object's observers notified of the change. default implementation is to cause the courier service to deliver to the interface controlled by my controller. Extensions can override.

Specified by:
update in interface Observer
Parameters:
o - the observable object.
arg - an argument passed to the notifyObservers method.

continueUpdate

protected void continueUpdate(Event event)
Complete the update, given an event that we know we need to act upon.

Parameters:
event - The event to process.

referencePath

protected String referencePath(String ref)
Compute the reference path (i.e. the container) for a given reference.

Parameters:
ref - The reference string.
Returns:
The reference root for the given reference.