com.opensymphony.oscache.base
Class Cache

java.lang.Object
  extended by com.opensymphony.oscache.base.Cache
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ServletCache

public class Cache
extends Object
implements Serializable

Provides an interface to the cache itself. Creating an instance of this class will create a cache that behaves according to its construction parameters. The public API provides methods to manage objects in the cache and configure any cache event listeners.

Version:
$Revision: 468 $
Author:
Mike Cannon-Brookes, Todd Gochenour, Francois Beauregard, Chris Miller
See Also:
Serialized Form

Field Summary
protected  EventListenerList listenerList
          A list of all registered event listeners for this cache.
static String NESTED_EVENT
          An event that origininated from within another event.
 
Constructor Summary
Cache(boolean useMemoryCaching, boolean unlimitedDiskCache, boolean overflowPersistence)
          Create a new Cache
Cache(boolean useMemoryCaching, boolean unlimitedDiskCache, boolean overflowPersistence, boolean blocking, String algorithmClass, int capacity)
          Create a new Cache.
 
Method Summary
 void addCacheEventListener(CacheEventListener listener)
          Register a listener for Cache events.
 void addCacheEventListener(CacheEventListener listener, Class clazz)
          Deprecated. use addCacheEventListener(CacheEventListener)
 void cancelUpdate(String key)
          Cancels any pending update for this cache entry.
protected  void clear()
          Completely clears the cache.
protected  void completeUpdate(String key)
          Removes the update state for the specified key and notifies any other threads that are waiting on this object.
 void flushAll(Date date)
          Flush all entries in the cache on the given date/time.
 void flushAll(Date date, String origin)
          Flush all entries in the cache on the given date/time.
 void flushEntry(String key)
          Flush the cache entry (if any) that corresponds to the cache key supplied.
 void flushEntry(String key, String origin)
          Flush the cache entry (if any) that corresponds to the cache key supplied.
 void flushGroup(String group)
          Flushes all objects that belong to the supplied group.
 void flushGroup(String group, String origin)
          Flushes all unexpired objects that belong to the supplied group.
 void flushPattern(String pattern)
          Deprecated. For performance and flexibility reasons it is preferable to store cache entries in groups and use the flushGroup(String) method instead of relying on pattern flushing.
 void flushPattern(String pattern, String origin)
          Deprecated. For performance and flexibility reasons it is preferable to store cache entries in groups and use the flushGroup(String, String) method instead of relying on pattern flushing.
protected  CacheEntry getCacheEntry(String key, EntryRefreshPolicy policy, String origin)
          Get an entry from this cache or create one if it doesn't exist.
 EventListenerList getCacheEventListenerList()
          Returns the list of all CacheEventListeners.
 int getCapacity()
           
 Object getFromCache(String key)
          Retrieve an object from the cache specifying its key.
 Object getFromCache(String key, int refreshPeriod)
          Retrieve an object from the cache specifying its key.
 Object getFromCache(String key, int refreshPeriod, String cronExpiry)
          Retrieve an object from the cache specifying its key.
 int getNbEntries()
          Deprecated. use getSize()
protected  int getNbUpdateState()
          Test support only: return the number of EntryUpdateState instances within the updateStates map.
 PersistenceListener getPersistenceListener()
          Retrieves the currently configured PersistenceListener.
 int getSize()
           
protected  EntryUpdateState getUpdateState(String key)
          Get the updating cache entry from the update map.
 boolean isFlushed(CacheEntry cacheEntry)
          Checks if the cache was flushed more recently than the CacheEntry provided.
protected  boolean isStale(CacheEntry cacheEntry, int refreshPeriod, String cronExpiry)
          Indicates whether or not the cache entry is stale.
 void putInCache(String key, Object content)
          Put an object in the cache specifying the key to use.
 void putInCache(String key, Object content, EntryRefreshPolicy policy)
          Put an object in the cache specifying the key and refresh policy to use.
 void putInCache(String key, Object content, String[] groups)
          Put in object into the cache, specifying both the key to use and the cache groups the object belongs to.
 void putInCache(String key, Object content, String[] groups, EntryRefreshPolicy policy, String origin)
          Put an object into the cache specifying both the key to use and the cache groups the object belongs to.
protected  void releaseUpdateState(EntryUpdateState state, String key)
          releases the usage that was made of the specified EntryUpdateState.
 void removeCacheEventListener(CacheEventListener listener)
          Unregister a listener for Cache events.
 void removeCacheEventListener(CacheEventListener listener, Class clazz)
          Deprecated. use instead removeCacheEventListener(CacheEventListener)
 void removeEntry(String key)
          Completely removes a cache entry from the cache and its associated cache groups.
protected  void removeEntry(String key, String origin)
          Completely removes a cache entry from the cache and its associated cache groups.
 void setCapacity(int capacity)
          Allows the capacity of the cache to be altered dynamically.
 void setPersistenceListener(PersistenceListener listener)
          Set the listener to use for data persistence.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NESTED_EVENT

public static final String NESTED_EVENT
An event that origininated from within another event.

See Also:
Constant Field Values

listenerList

protected EventListenerList listenerList
A list of all registered event listeners for this cache.

Constructor Detail

Cache

public Cache(boolean useMemoryCaching,
             boolean unlimitedDiskCache,
             boolean overflowPersistence)
Create a new Cache

Parameters:
useMemoryCaching - Specify if the memory caching is going to be used
unlimitedDiskCache - Specify if the disk caching is unlimited
overflowPersistence - Specify if the persistent cache is used in overflow only mode

Cache

public Cache(boolean useMemoryCaching,
             boolean unlimitedDiskCache,
             boolean overflowPersistence,
             boolean blocking,
             String algorithmClass,
             int capacity)
Create a new Cache. If a valid algorithm class is specified, it will be used for this cache. Otherwise if a capacity is specified, it will use LRUCache. If no algorithm or capacity is specified UnlimitedCache is used.

Parameters:
useMemoryCaching - Specify if the memory caching is going to be used
unlimitedDiskCache - Specify if the disk caching is unlimited
overflowPersistence - Specify if the persistent cache is used in overflow only mode
blocking - This parameter takes effect when a cache entry has just expired and several simultaneous requests try to retrieve it. While one request is rebuilding the content, the other requests will either block and wait for the new content (blocking == true) or instead receive a copy of the stale content so they don't have to wait (blocking == false). the default is false, which provides better performance but at the expense of slightly stale data being served.
algorithmClass - The class implementing the desired algorithm
capacity - The capacity
See Also:
LRUCache, UnlimitedCache
Method Detail

getCapacity

public int getCapacity()
Returns:
the maximum number of items to cache can hold.

setCapacity

public void setCapacity(int capacity)
Allows the capacity of the cache to be altered dynamically. Note that some cache implementations may choose to ignore this setting (eg the UnlimitedCache ignores this call).

Parameters:
capacity - the maximum number of items to hold in the cache.

isFlushed

public boolean isFlushed(CacheEntry cacheEntry)
Checks if the cache was flushed more recently than the CacheEntry provided. Used to determine whether to refresh the particular CacheEntry.

Parameters:
cacheEntry - The cache entry which we're seeing whether to refresh
Returns:
Whether or not the cache has been flushed more recently than this cache entry was updated.

getFromCache

public Object getFromCache(String key)
                    throws NeedsRefreshException
Retrieve an object from the cache specifying its key.

Parameters:
key - Key of the object in the cache.
Returns:
The object from cache
Throws:
NeedsRefreshException - Thrown when the object either doesn't exist, or exists but is stale. When this exception occurs, the CacheEntry corresponding to the supplied key will be locked and other threads requesting this entry will potentially be blocked until the caller repopulates the cache. If the caller choses not to repopulate the cache, they must instead call cancelUpdate(String).

getFromCache

public Object getFromCache(String key,
                           int refreshPeriod)
                    throws NeedsRefreshException
Retrieve an object from the cache specifying its key.

Parameters:
key - Key of the object in the cache.
refreshPeriod - How long before the object needs refresh. To allow the object to stay in the cache indefinitely, supply a value of CacheEntry.INDEFINITE_EXPIRY.
Returns:
The object from cache
Throws:
NeedsRefreshException - Thrown when the object either doesn't exist, or exists but is stale. When this exception occurs, the CacheEntry corresponding to the supplied key will be locked and other threads requesting this entry will potentially be blocked until the caller repopulates the cache. If the caller choses not to repopulate the cache, they must instead call cancelUpdate(String).

getFromCache

public Object getFromCache(String key,
                           int refreshPeriod,
                           String cronExpiry)
                    throws NeedsRefreshException
Retrieve an object from the cache specifying its key.

Parameters:
key - Key of the object in the cache.
refreshPeriod - How long before the object needs refresh. To allow the object to stay in the cache indefinitely, supply a value of CacheEntry.INDEFINITE_EXPIRY.
cronExpiry - A cron expression that specifies fixed date(s) and/or time(s) that this cache entry should expire on.
Returns:
The object from cache
Throws:
NeedsRefreshException - Thrown when the object either doesn't exist, or exists but is stale. When this exception occurs, the CacheEntry corresponding to the supplied key will be locked and other threads requesting this entry will potentially be blocked until the caller repopulates the cache. If the caller choses not to repopulate the cache, they must instead call cancelUpdate(String).

setPersistenceListener

public void setPersistenceListener(PersistenceListener listener)
Set the listener to use for data persistence. Only one PersistenceListener can be configured per cache.

Parameters:
listener - The implementation of a persistance listener

getPersistenceListener

public PersistenceListener getPersistenceListener()
Retrieves the currently configured PersistenceListener.

Returns:
the cache's PersistenceListener, or null if no listener is configured.

addCacheEventListener

public void addCacheEventListener(CacheEventListener listener)
Register a listener for Cache events. The listener must implement one of the child interfaces of the CacheEventListener interface.

Parameters:
listener - The object that listens to events.
Since:
2.4

addCacheEventListener

public void addCacheEventListener(CacheEventListener listener,
                                  Class clazz)
Deprecated. use addCacheEventListener(CacheEventListener)

Register a listener for Cache events. The listener must implement one of the child interfaces of the CacheEventListener interface.

Parameters:
listener - The object that listens to events.
clazz - the type of the listener to be added

getCacheEventListenerList

public EventListenerList getCacheEventListenerList()
Returns the list of all CacheEventListeners.

Returns:
the CacheEventListener's list of the Cache

cancelUpdate

public void cancelUpdate(String key)
Cancels any pending update for this cache entry. This should only be called by the thread that is responsible for performing the update ie the thread that received the original NeedsRefreshException.

If a cache entry is not updated (via putInCache(java.lang.String, java.lang.Object) and this method is not called to let OSCache know the update will not be forthcoming, subsequent requests for this cache entry will either block indefinitely (if this is a new cache entry or cache.blocking=true), or forever get served stale content. Note however that there is no harm in cancelling an update on a key that either does not exist or is not currently being updated.

Parameters:
key - The key for the cache entry in question.
Throws:
IllegalStateException - if the cache entry isn't in the state UPDATE_IN_PROGRESS

flushAll

public void flushAll(Date date)
Flush all entries in the cache on the given date/time.

Parameters:
date - The date at which all cache entries will be flushed.

flushAll

public void flushAll(Date date,
                     String origin)
Flush all entries in the cache on the given date/time.

Parameters:
date - The date at which all cache entries will be flushed.
origin - The origin of this flush request (optional)

flushEntry

public void flushEntry(String key)
Flush the cache entry (if any) that corresponds to the cache key supplied. This call will flush the entry from the cache and remove the references to it from any cache groups that it is a member of. On completion of the flush, a CacheEntryEventType.ENTRY_FLUSHED event is fired.

Parameters:
key - The key of the entry to flush

flushEntry

public void flushEntry(String key,
                       String origin)
Flush the cache entry (if any) that corresponds to the cache key supplied. This call will mark the cache entry as flushed so that the next access to it will cause a NeedsRefreshException. On completion of the flush, a CacheEntryEventType.ENTRY_FLUSHED event is fired.

Parameters:
key - The key of the entry to flush
origin - The origin of this flush request (optional)

flushGroup

public void flushGroup(String group)
Flushes all objects that belong to the supplied group. On completion this method fires a CacheEntryEventType.GROUP_FLUSHED event.

Parameters:
group - The group to flush

flushGroup

public void flushGroup(String group,
                       String origin)
Flushes all unexpired objects that belong to the supplied group. On completion this method fires a CacheEntryEventType.GROUP_FLUSHED event.

Parameters:
group - The group to flush
origin - The origin of this flush event (optional)

flushPattern

public void flushPattern(String pattern)
Deprecated. For performance and flexibility reasons it is preferable to store cache entries in groups and use the flushGroup(String) method instead of relying on pattern flushing.

Flush all entries with keys that match a given pattern

Parameters:
pattern - The key must contain this given value

flushPattern

public void flushPattern(String pattern,
                         String origin)
Deprecated. For performance and flexibility reasons it is preferable to store cache entries in groups and use the flushGroup(String, String) method instead of relying on pattern flushing.

Flush all entries with keys that match a given pattern

Parameters:
pattern - The key must contain this given value
origin - The origin of this flush request

putInCache

public void putInCache(String key,
                       Object content)
Put an object in the cache specifying the key to use.

Parameters:
key - Key of the object in the cache.
content - The object to cache.

putInCache

public void putInCache(String key,
                       Object content,
                       EntryRefreshPolicy policy)
Put an object in the cache specifying the key and refresh policy to use.

Parameters:
key - Key of the object in the cache.
content - The object to cache.
policy - Object that implements refresh policy logic

putInCache

public void putInCache(String key,
                       Object content,
                       String[] groups)
Put in object into the cache, specifying both the key to use and the cache groups the object belongs to.

Parameters:
key - Key of the object in the cache
content - The object to cache
groups - The cache groups to add the object to

putInCache

public void putInCache(String key,
                       Object content,
                       String[] groups,
                       EntryRefreshPolicy policy,
                       String origin)
Put an object into the cache specifying both the key to use and the cache groups the object belongs to.

Parameters:
key - Key of the object in the cache
groups - The cache groups to add the object to
content - The object to cache
policy - Object that implements the refresh policy logic

removeCacheEventListener

public void removeCacheEventListener(CacheEventListener listener,
                                     Class clazz)
Deprecated. use instead removeCacheEventListener(CacheEventListener)

Unregister a listener for Cache events.

Parameters:
listener - The object that currently listens to events.
clazz - The registrated class of listening object.

removeCacheEventListener

public void removeCacheEventListener(CacheEventListener listener)
Unregister a listener for Cache events.

Parameters:
listener - The object that currently listens to events.
Since:
2.4

getCacheEntry

protected CacheEntry getCacheEntry(String key,
                                   EntryRefreshPolicy policy,
                                   String origin)
Get an entry from this cache or create one if it doesn't exist.

Parameters:
key - The key of the cache entry
policy - Object that implements refresh policy logic
origin - The origin of request (optional)
Returns:
CacheEntry for the specified key.

isStale

protected boolean isStale(CacheEntry cacheEntry,
                          int refreshPeriod,
                          String cronExpiry)
Indicates whether or not the cache entry is stale.

Parameters:
cacheEntry - The cache entry to test the freshness of.
refreshPeriod - The maximum allowable age of the entry, in seconds.
cronExpiry - A cron expression specifying absolute date(s) and/or time(s) that the cache entry should expire at. If the cache entry was refreshed prior to the most recent match for the cron expression, the entry will be considered stale.
Returns:
true if the entry is stale, false otherwise.

getUpdateState

protected EntryUpdateState getUpdateState(String key)
Get the updating cache entry from the update map. If one is not found, create a new one (with state EntryUpdateState.NOT_YET_UPDATING) and add it to the map.

Parameters:
key - The cache key for this entry
Returns:
the CacheEntry that was found (or added to) the updatingEntries map.

releaseUpdateState

protected void releaseUpdateState(EntryUpdateState state,
                                  String key)
releases the usage that was made of the specified EntryUpdateState. When this reaches zero, the entry is removed from the map.

Parameters:
state - the state to release the usage of
key - the associated key.

clear

protected void clear()
Completely clears the cache.


completeUpdate

protected void completeUpdate(String key)
Removes the update state for the specified key and notifies any other threads that are waiting on this object. This is called automatically by the putInCache(java.lang.String, java.lang.Object) method, so it is possible that no EntryUpdateState was hold when this method is called.

Parameters:
key - The cache key that is no longer being updated.

removeEntry

public void removeEntry(String key)
Completely removes a cache entry from the cache and its associated cache groups.

Parameters:
key - The key of the entry to remove.

removeEntry

protected void removeEntry(String key,
                           String origin)
Completely removes a cache entry from the cache and its associated cache groups.

Parameters:
key - The key of the entry to remove.
origin - The origin of this remove request.

getSize

public int getSize()
Returns:
the total number of cache entries held in this cache.

getNbUpdateState

protected int getNbUpdateState()
Test support only: return the number of EntryUpdateState instances within the updateStates map.


getNbEntries

public int getNbEntries()
Deprecated. use getSize()

Test support only: return the number of entries currently in the cache map


OSCache Project Page