| java.lang.Object
 com.opensymphony.oscache.base.Cache
All known Subclasses: com.opensymphony.oscache.web.ServletCache,
| Cache | | public class Cache implements Serializable(Code) | | 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
author:
Todd Gochenour
author:
Francois Beauregard
author:
Chris Miller |
| Constructor Summary | |
| public | Cache(boolean useMemoryCaching, boolean unlimitedDiskCache, boolean overflowPersistence)
| | 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.
See Also: com.opensymphony.oscache.base.algorithm.LRUCache
See Also: com.opensymphony.oscache.base.algorithm.UnlimitedCache
Parameters:
useMemoryCaching - Specify if the memory caching is going to be used
Parameters:
unlimitedDiskCache - Specify if the disk caching is unlimited
Parameters:
overflowPersistence - Specify if the persistent cache is used in overflow only mode
Parameters:
blocking - This parameter takes effect when a cache entry hasjust expired and several simultaneous requests try to retrieve it. |
| Method Summary | |
| public void | addCacheEventListener(CacheEventListener listener)
Register a listener for Cache events. | | public void | addCacheEventListener(CacheEventListener listener, Class clazz)
Register a listener for Cache events. | | public 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. | | public void | flushAll(Date date)
Flush all entries in the cache on the given date/time. | | public void | flushAll(Date date, String origin)
Flush all entries in the cache on the given date/time. | | 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. | | 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 . | | public void | flushGroup(String group)
Flushes all objects that belong to the supplied group. | | public void | flushGroup(String group, String origin)
Flushes all unexpired objects that belong to the supplied group. | | public void | flushPattern(String pattern)
| | public void | flushPattern(String pattern, String origin)
| | protected CacheEntry | getCacheEntry(String key, EntryRefreshPolicy policy, String origin)
Get an entry from this cache or create one if it doesn't exist. | | public EventListenerList | getCacheEventListenerList()
Returns the list of all CacheEventListeners. | | public int | getCapacity()
| | public Object | getFromCache(String key)
Retrieve an object from the cache specifying its key.
Parameters:
key - Key of the object in the cache. | | public Object | getFromCache(String key, int refreshPeriod)
Retrieve an object from the cache specifying its key.
Parameters:
key - Key of the object in the cache.
Parameters:
refreshPeriod - How long before the object needs refresh. | | public Object | getFromCache(String key, int refreshPeriod, String cronExpiry)
Retrieve an object from the cache specifying its key.
Parameters:
key - Key of the object in the cache.
Parameters:
refreshPeriod - How long before the object needs refresh. | | public int | getNbEntries()
| | protected int | getNbUpdateState()
Test support only: return the number of EntryUpdateState instances within the updateStates map. | | public PersistenceListener | getPersistenceListener()
Retrieves the currently configured PersistenceListener. | | public int | getSize()
the total number of cache entries held in this cache. | | protected EntryUpdateState | getUpdateState(String key)
Get the updating cache entry from the update map. | | public 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.
Parameters:
cacheEntry - The cache entry to test the freshness of.
Parameters:
refreshPeriod - The maximum allowable age of the entry, in seconds.
Parameters:
cronExpiry - A cron expression specifying absolute date(s) and/or time(s)that the cache entry should expire at. | | public void | putInCache(String key, Object content)
Put an object in the cache specifying the key to use. | | public void | putInCache(String key, Object content, EntryRefreshPolicy policy)
Put an object in the cache specifying the key and refresh policy to use. | | 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. | | 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. | | protected void | releaseUpdateState(EntryUpdateState state, String key)
releases the usage that was made of the specified EntryUpdateState. | | public void | removeCacheEventListener(CacheEventListener listener, Class clazz)
Unregister a listener for Cache events. | | public void | removeCacheEventListener(CacheEventListener listener)
Unregister a listener for Cache events. | | public 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. | | public void | setCapacity(int capacity)
Allows the capacity of the cache to be altered dynamically. | | public void | setPersistenceListener(PersistenceListener listener)
Set the listener to use for data persistence. |
| NESTED_EVENT | | final public static String NESTED_EVENT(Code) | | An event that origininated from within another event.
|
| listenerList | | protected EventListenerList listenerList(Code) | | A list of all registered event listeners for this cache.
|
| Cache | | public Cache(boolean useMemoryCaching, boolean unlimitedDiskCache, boolean overflowPersistence)(Code) | | Create a new Cache
Parameters:
useMemoryCaching - Specify if the memory caching is going to be used
Parameters:
unlimitedDiskCache - Specify if the disk caching is unlimited
Parameters:
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)(Code) | | 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.
See Also: com.opensymphony.oscache.base.algorithm.LRUCache
See Also: com.opensymphony.oscache.base.algorithm.UnlimitedCache
Parameters:
useMemoryCaching - Specify if the memory caching is going to be used
Parameters:
unlimitedDiskCache - Specify if the disk caching is unlimited
Parameters:
overflowPersistence - Specify if the persistent cache is used in overflow only mode
Parameters:
blocking - This parameter takes effect when a cache entry hasjust expired and several simultaneous requests try to retrieve it. Whileone request is rebuilding the content, the other requests will eitherblock and wait for the new content (blocking == true) orinstead 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 staledata being served.
Parameters:
algorithmClass - The class implementing the desired algorithm
Parameters:
capacity - The capacity |
| addCacheEventListener | | public void addCacheEventListener(CacheEventListener listener)(Code) | | 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 |
| cancelUpdate | | public void cancelUpdate(String key)(Code) | | 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
Cache.putInCache 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 |
| clear | | protected void clear()(Code) | | Completely clears the cache.
|
| completeUpdate | | protected void completeUpdate(String key)(Code) | | 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
Cache.putInCache 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. |
| flushAll | | public void flushAll(Date date)(Code) | | 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)(Code) | | Flush all entries in the cache on the given date/time.
Parameters:
date - The date at which all cache entries will be flushed.
Parameters:
origin - The origin of this flush request (optional) |
| flushEntry | | public void flushEntry(String key)(Code) | | 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)(Code) | | 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
Parameters:
origin - The origin of this flush request (optional) |
| flushGroup | | public void flushGroup(String group)(Code) | | 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)(Code) | | 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
Parameters:
origin - The origin of this flush event (optional) |
| flushPattern | | public void flushPattern(String pattern)(Code) | | Flush all entries with keys that match a given pattern
Parameters:
pattern - The key must contain this given valueCache.flushGroup(String) |
| flushPattern | | public void flushPattern(String pattern, String origin)(Code) | | Flush all entries with keys that match a given pattern
Parameters:
pattern - The key must contain this given value
Parameters:
origin - The origin of this flush requestCache.flushGroup(String,String) |
| getCacheEntry | | protected CacheEntry getCacheEntry(String key, EntryRefreshPolicy policy, String origin)(Code) | | Get an entry from this cache or create one if it doesn't exist.
Parameters:
key - The key of the cache entry
Parameters:
policy - Object that implements refresh policy logic
Parameters:
origin - The origin of request (optional) CacheEntry for the specified key. |
| getCacheEventListenerList | | public EventListenerList getCacheEventListenerList()(Code) | | Returns the list of all CacheEventListeners.
the CacheEventListener's list of the Cache |
| getCapacity | | public int getCapacity()(Code) | | the maximum number of items to cache can hold. |
| getFromCache | | public Object getFromCache(String key) throws NeedsRefreshException(Code) | | Retrieve an object from the cache specifying its key.
Parameters:
key - Key of the object in the cache. The object from cache
throws:
NeedsRefreshException - Thrown when the object eitherdoesn't exist, or exists but is stale. When this exception occurs,the CacheEntry corresponding to the supplied key will be lockedand other threads requesting this entry will potentially be blockeduntil the caller repopulates the cache. If the caller choses notto repopulate the cache, they must instead callCache.cancelUpdate(String). |
| getFromCache | | public Object getFromCache(String key, int refreshPeriod) throws NeedsRefreshException(Code) | | Retrieve an object from the cache specifying its key.
Parameters:
key - Key of the object in the cache.
Parameters:
refreshPeriod - How long before the object needs refresh. Toallow the object to stay in the cache indefinitely, supply a valueof CacheEntry.INDEFINITE_EXPIRY. The object from cache
throws:
NeedsRefreshException - Thrown when the object eitherdoesn't exist, or exists but is stale. When this exception occurs,the CacheEntry corresponding to the supplied key will be lockedand other threads requesting this entry will potentially be blockeduntil the caller repopulates the cache. If the caller choses notto repopulate the cache, they must instead callCache.cancelUpdate(String). |
| getFromCache | | public Object getFromCache(String key, int refreshPeriod, String cronExpiry) throws NeedsRefreshException(Code) | | Retrieve an object from the cache specifying its key.
Parameters:
key - Key of the object in the cache.
Parameters:
refreshPeriod - How long before the object needs refresh. Toallow the object to stay in the cache indefinitely, supply a valueof CacheEntry.INDEFINITE_EXPIRY.
Parameters:
cronExpiry - A cron expression that specifies fixed date(s)and/or time(s) that this cache entry shouldexpire on. The object from cache
throws:
NeedsRefreshException - Thrown when the object eitherdoesn't exist, or exists but is stale. When this exception occurs,the CacheEntry corresponding to the supplied key will be lockedand other threads requesting this entry will potentially be blockeduntil the caller repopulates the cache. If the caller choses notto repopulate the cache, they must instead callCache.cancelUpdate(String). |
| getNbEntries | | public int getNbEntries()(Code) | | Test support only: return the number of entries currently in the cache map
|
| getNbUpdateState | | protected int getNbUpdateState()(Code) | | Test support only: return the number of EntryUpdateState instances within the updateStates map.
|
| getPersistenceListener | | public PersistenceListener getPersistenceListener()(Code) | | Retrieves the currently configured PersistenceListener.
the cache's PersistenceListener, or nullif no listener is configured. |
| getSize | | public int getSize()(Code) | | the total number of cache entries held in this cache. |
| getUpdateState | | protected EntryUpdateState getUpdateState(String key)(Code) | | 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 the CacheEntry that was found (or added to) the updatingEntriesmap. |
| isFlushed | | public boolean isFlushed(CacheEntry cacheEntry)(Code) | | 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 Whether or not the cache has been flushed more recently than this cache entry was updated. |
| isStale | | protected boolean isStale(CacheEntry cacheEntry, int refreshPeriod, String cronExpiry)(Code) | | Indicates whether or not the cache entry is stale.
Parameters:
cacheEntry - The cache entry to test the freshness of.
Parameters:
refreshPeriod - The maximum allowable age of the entry, in seconds.
Parameters:
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 tothe most recent match for the cron expression, the entry will be considered stale. true if the entry is stale, false otherwise. |
| putInCache | | public void putInCache(String key, Object content)(Code) | | Put an object in the cache specifying the key to use.
Parameters:
key - Key of the object in the cache.
Parameters:
content - The object to cache. |
| putInCache | | public void putInCache(String key, Object content, EntryRefreshPolicy policy)(Code) | | Put an object in the cache specifying the key and refresh policy to use.
Parameters:
key - Key of the object in the cache.
Parameters:
content - The object to cache.
Parameters:
policy - Object that implements refresh policy logic |
| putInCache | | public void putInCache(String key, Object content, String[] groups)(Code) | | 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
Parameters:
content - The object to cache
Parameters:
groups - The cache groups to add the object to |
| putInCache | | public void putInCache(String key, Object content, String[] groups, EntryRefreshPolicy policy, String origin)(Code) | | 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
Parameters:
groups - The cache groups to add the object to
Parameters:
content - The object to cache
Parameters:
policy - Object that implements the refresh policy logic |
| releaseUpdateState | | protected void releaseUpdateState(EntryUpdateState state, String key)(Code) | | 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
Parameters:
key - the associated key. |
| removeCacheEventListener | | public void removeCacheEventListener(CacheEventListener listener)(Code) | | Unregister a listener for Cache events.
Parameters:
listener - The object that currently listens to events.
since:
2.4 |
| removeEntry | | public void removeEntry(String key)(Code) | | 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)(Code) | | Completely removes a cache entry from the cache and its associated cache
groups.
Parameters:
key - The key of the entry to remove.
Parameters:
origin - The origin of this remove request. |
| setCapacity | | public void setCapacity(int capacity)(Code) | | 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. |
| setPersistenceListener | | public void setPersistenceListener(PersistenceListener listener)(Code) | | Set the listener to use for data persistence. Only one
PersistenceListener can be configured per cache.
Parameters:
listener - The implementation of a persistance listener |
|
|