|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.opensymphony.oscache.base.Cache
public class Cache
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.
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 |
---|
public static final String NESTED_EVENT
protected EventListenerList listenerList
Constructor Detail |
---|
public Cache(boolean useMemoryCaching, boolean unlimitedDiskCache, boolean overflowPersistence)
useMemoryCaching
- Specify if the memory caching is going to be usedunlimitedDiskCache
- Specify if the disk caching is unlimitedoverflowPersistence
- Specify if the persistent cache is used in overflow only modepublic Cache(boolean useMemoryCaching, boolean unlimitedDiskCache, boolean overflowPersistence, boolean blocking, String algorithmClass, int capacity)
useMemoryCaching
- Specify if the memory caching is going to be usedunlimitedDiskCache
- Specify if the disk caching is unlimitedoverflowPersistence
- Specify if the persistent cache is used in overflow only modeblocking
- 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 algorithmcapacity
- The capacityLRUCache
,
UnlimitedCache
Method Detail |
---|
public int getCapacity()
public void setCapacity(int capacity)
UnlimitedCache
ignores this call).
capacity
- the maximum number of items to hold in the cache.public boolean isFlushed(CacheEntry cacheEntry)
cacheEntry
- The cache entry which we're seeing whether to refresh
public Object getFromCache(String key) throws NeedsRefreshException
key
- Key of the object in the cache.
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)
.public Object getFromCache(String key, int refreshPeriod) throws NeedsRefreshException
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
.
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)
.public Object getFromCache(String key, int refreshPeriod, String cronExpiry) throws NeedsRefreshException
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.
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)
.public void setPersistenceListener(PersistenceListener listener)
PersistenceListener
can be configured per cache.
listener
- The implementation of a persistance listenerpublic PersistenceListener getPersistenceListener()
PersistenceListener
.
PersistenceListener
, or null
if no listener is configured.public void addCacheEventListener(CacheEventListener listener)
CacheEventListener
interface.
listener
- The object that listens to events.public void addCacheEventListener(CacheEventListener listener, Class clazz)
addCacheEventListener(CacheEventListener)
CacheEventListener
interface.
listener
- The object that listens to events.clazz
- the type of the listener to be addedpublic EventListenerList getCacheEventListenerList()
public void cancelUpdate(String key)
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.
key
- The key for the cache entry in question.
IllegalStateException
- if the cache entry isn't in the state UPDATE_IN_PROGRESSpublic void flushAll(Date date)
date
- The date at which all cache entries will be flushed.public void flushAll(Date date, String origin)
date
- The date at which all cache entries will be flushed.origin
- The origin of this flush request (optional)public void flushEntry(String key)
key
- The key of the entry to flushpublic void flushEntry(String key, String origin)
NeedsRefreshException
. On completion of the
flush, a CacheEntryEventType.ENTRY_FLUSHED event is fired.
key
- The key of the entry to flushorigin
- The origin of this flush request (optional)public void flushGroup(String group)
group
- The group to flushpublic void flushGroup(String group, String origin)
group
- The group to flushorigin
- The origin of this flush event (optional)public void flushPattern(String pattern)
flushGroup(String)
method
instead of relying on pattern flushing.
pattern
- The key must contain this given valuepublic void flushPattern(String pattern, String origin)
flushGroup(String, String)
method instead of relying on pattern flushing.
pattern
- The key must contain this given valueorigin
- The origin of this flush requestpublic void putInCache(String key, Object content)
key
- Key of the object in the cache.content
- The object to cache.public void putInCache(String key, Object content, EntryRefreshPolicy policy)
key
- Key of the object in the cache.content
- The object to cache.policy
- Object that implements refresh policy logicpublic void putInCache(String key, Object content, String[] groups)
key
- Key of the object in the cachecontent
- The object to cachegroups
- The cache groups to add the object topublic void putInCache(String key, Object content, String[] groups, EntryRefreshPolicy policy, String origin)
key
- Key of the object in the cachegroups
- The cache groups to add the object tocontent
- The object to cachepolicy
- Object that implements the refresh policy logicpublic void removeCacheEventListener(CacheEventListener listener, Class clazz)
removeCacheEventListener(CacheEventListener)
listener
- The object that currently listens to events.clazz
- The registrated class of listening object.public void removeCacheEventListener(CacheEventListener listener)
listener
- The object that currently listens to events.protected CacheEntry getCacheEntry(String key, EntryRefreshPolicy policy, String origin)
key
- The key of the cache entrypolicy
- Object that implements refresh policy logicorigin
- The origin of request (optional)
protected boolean isStale(CacheEntry cacheEntry, int refreshPeriod, String cronExpiry)
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.
true
if the entry is stale, false
otherwise.protected EntryUpdateState getUpdateState(String key)
EntryUpdateState.NOT_YET_UPDATING
)
and add it to the map.
key
- The cache key for this entry
protected void releaseUpdateState(EntryUpdateState state, String key)
state
- the state to release the usage ofkey
- the associated key.protected void clear()
protected void completeUpdate(String key)
putInCache(java.lang.String, java.lang.Object)
method, so it is possible that no EntryUpdateState was hold
when this method is called.
key
- The cache key that is no longer being updated.public void removeEntry(String key)
key
- The key of the entry to remove.protected void removeEntry(String key, String origin)
key
- The key of the entry to remove.origin
- The origin of this remove request.public int getSize()
protected int getNbUpdateState()
public int getNbEntries()
|
OSCache Project Page | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |