* To avoid data races, values in this map should remain present during the whole time distinct threads deal with the
* same key. We implement this using explicit reference counting in the EntryUpdateState instance, to be able to clean up
* the map once all threads have declared they are done accessing/updating a given key.
*
* It is not possible to locate this into the CacheEntry because this would require to have a CacheEntry instance for all cache misses, and
* may therefore generate a memory leak. More over, the CacheEntry instance may not be hold in memory in the case no
* memory cache is configured.
*/
private Map updateStates = new HashMap();
/**
* Indicates whether the cache blocks requests until new content has
* been generated or just serves stale content instead.
*/
private boolean blocking = false;
/**
* Create a new Cache
*
* @param useMemoryCaching Specify if the memory caching is going to be used
* @param unlimitedDiskCache Specify if the disk caching is unlimited
* @param overflowPersistence Specify if the persistent cache is used in overflow only mode
*/
public Cache(boolean useMemoryCaching, boolean unlimitedDiskCache, boolean overflowPersistence) {
this(useMemoryCaching, unlimitedDiskCache, overflowPersistence, false, null, 0);
}
/**
* 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 com.opensymphony.oscache.base.algorithm.LRUCache
* @see com.opensymphony.oscache.base.algorithm.UnlimitedCache
* @param useMemoryCaching Specify if the memory caching is going to be used
* @param unlimitedDiskCache Specify if the disk caching is unlimited
* @param overflowPersistence Specify if the persistent cache is used in overflow only mode
* @param 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.
* @param algorithmClass The class implementing the desired algorithm
* @param capacity The capacity
*/
public Cache(boolean useMemoryCaching, boolean unlimitedDiskCache, boolean overflowPersistence, boolean blocking, String algorithmClass, int capacity) {
// Instantiate the algo class if valid
if (((algorithmClass != null) && (algorithmClass.length() > 0)) && (capacity > 0)) {
try {
cacheMap = (AbstractConcurrentReadCache) Class.forName(algorithmClass).newInstance();
cacheMap.setMaxEntries(capacity);
} catch (Exception e) {
log.error("Invalid class name for cache algorithm class. " + e.toString());
}
}
if (cacheMap == null) {
// If we have a capacity, use LRU cache otherwise use unlimited Cache
if (capacity > 0) {
cacheMap = new LRUCache(capacity);
} else {
cacheMap = new UnlimitedCache();
}
}
cacheMap.setUnlimitedDiskCache(unlimitedDiskCache);
cacheMap.setOverflowPersistence(overflowPersistence);
cacheMap.setMemoryCaching(useMemoryCaching);
this.blocking = blocking;
}
/**
* @return the maximum number of items to cache can hold.
*/
public int getCapacity() {
return cacheMap.getMaxEntries();
}
/**
* Allows the capacity of the cache to be altered dynamically. Note that
* some cache implementations may choose to ignore this setting (eg the
* {@link UnlimitedCache} ignores this call).
*
* @param capacity the maximum number of items to hold in the cache.
*/
public void setCapacity(int capacity) {
cacheMap.setMaxEntries(capacity);
}
/**
* Checks if the cache was flushed more recently than the CacheEntry provided.
* Used to determine whether to refresh the particular CacheEntry.
*
* @param cacheEntry The cache entry which we're seeing whether to refresh
* @return Whether or not the cache has been flushed more recently than this cache entry was updated.
*/
public boolean isFlushed(CacheEntry cacheEntry) {
if (flushDateTime != null) {
final long lastUpdate = cacheEntry.getLastUpdate();
final long flushTime = flushDateTime.getTime();
// CACHE-241: check flushDateTime with current time also
return (flushTime <= System.currentTimeMillis()) && (flushTime >= lastUpdate);
} else {
return false;
}
}
/**
* Retrieve an object from the cache specifying its key.
*
* @param key Key of the object in the cache.
*
* @return 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
* {@link #cancelUpdate(String)}.
*/
public Object getFromCache(String key) throws NeedsRefreshException {
return getFromCache(key, CacheEntry.INDEFINITE_EXPIRY, null);
}
/**
* Retrieve an object from the cache specifying its key.
*
* @param key Key of the object in the cache.
* @param refreshPeriod How long before the object needs refresh. To
* allow the object to stay in the cache indefinitely, supply a value
* of {@link CacheEntry#INDEFINITE_EXPIRY}.
*
* @return 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
* {@link #cancelUpdate(String)}.
*/
public Object getFromCache(String key, int refreshPeriod) throws NeedsRefreshException {
return getFromCache(key, refreshPeriod, null);
}
/**
* Retrieve an object from the cache specifying its key.
*
* @param key Key of the object in the cache.
* @param refreshPeriod How long before the object needs refresh. To
* allow the object to stay in the cache indefinitely, supply a value
* of {@link CacheEntry#INDEFINITE_EXPIRY}.
* @param cronExpiry A cron expression that specifies fixed date(s)
* and/or time(s) that this cache entry should
* expire on.
*
* @return 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
* {@link #cancelUpdate(String)}.
*/
public Object getFromCache(String key, int refreshPeriod, String cronExpiry) throws NeedsRefreshException {
CacheEntry cacheEntry = this.getCacheEntry(key, null, null);
Object content = cacheEntry.getContent();
CacheMapAccessEventType accessEventType = CacheMapAccessEventType.HIT;
boolean reload = false;
// Check if this entry has expired or has not yet been added to the cache. If
// so, we need to decide whether to block, serve stale content or throw a
// NeedsRefreshException
if (this.isStale(cacheEntry, refreshPeriod, cronExpiry)) {
//Get access to the EntryUpdateState instance and increment the usage count during the potential sleep
EntryUpdateState updateState = getUpdateState(key);
try {
synchronized (updateState) {
if (updateState.isAwaitingUpdate() || updateState.isCancelled()) {
// No one else is currently updating this entry - grab ownership
updateState.startUpdate();
if (cacheEntry.isNew()) {
accessEventType = CacheMapAccessEventType.MISS;
} else {
accessEventType = CacheMapAccessEventType.STALE_HIT;
}
} else if (updateState.isUpdating()) {
// Another thread is already updating the cache. We block if this
// is a new entry, or blocking mode is enabled. Either putInCache()
// or cancelUpdate() can cause this thread to resume.
if (cacheEntry.isNew() || blocking) {
do {
try {
updateState.wait();
} catch (InterruptedException e) {
}
} while (updateState.isUpdating());
if (updateState.isCancelled()) {
// The updating thread canceled the update, let this one have a go.
// This increments the usage count for this EntryUpdateState instance
updateState.startUpdate();
if (cacheEntry.isNew()) {
accessEventType = CacheMapAccessEventType.MISS;
} else {
accessEventType = CacheMapAccessEventType.STALE_HIT;
}
} else if (updateState.isComplete()) {
reload = true;
} else {
log.error("Invalid update state for cache entry " + key);
}
}
} else {
reload = true;
}
}
} finally {
//Make sure we release the usage count for this EntryUpdateState since we don't use it anymore. If the current thread started the update, then the counter was
//increased by one in startUpdate()
releaseUpdateState(updateState, key);
}
}
// If reload is true then another thread must have successfully rebuilt the cache entry
if (reload) {
cacheEntry = (CacheEntry) cacheMap.get(key);
if (cacheEntry != null) {
content = cacheEntry.getContent();
} else {
log.error("Could not reload cache entry after waiting for it to be rebuilt");
}
}
dispatchCacheMapAccessEvent(accessEventType, cacheEntry, null);
// If we didn't end up getting a hit then we need to throw a NRE
if (accessEventType != CacheMapAccessEventType.HIT) {
throw new NeedsRefreshException(content);
}
return content;
}
/**
* Set the listener to use for data persistence. Only one
* PersistenceListener can be configured per cache.
*
* @param listener The implementation of a persistance listener
*/
public void setPersistenceListener(PersistenceListener listener) {
cacheMap.setPersistenceListener(listener);
}
/**
* Retrieves the currently configured PersistenceListener.
*
* @return the cache's PersistenceListener, or null
* if no listener is configured.
*/
public PersistenceListener getPersistenceListener() {
return cacheMap.getPersistenceListener();
}
/**
* Register a listener for Cache events. The listener must implement
* one of the child interfaces of the {@link CacheEventListener} interface.
*
* @param listener The object that listens to events.
* @since 2.4
*/
public void addCacheEventListener(CacheEventListener listener) {
listenerList.add(CacheEventListener.class, listener);
// listenerList.add(listener.getClass(), listener);
}
/**
* Register a listener for Cache events. The listener must implement
* one of the child interfaces of the {@link CacheEventListener} interface.
*
* @param listener The object that listens to events.
* @param clazz the type of the listener to be added
* @deprecated use {@link #addCacheEventListener(CacheEventListener)}
*/
public void addCacheEventListener(CacheEventListener listener, Class clazz) {
if (CacheEventListener.class.isAssignableFrom(clazz)) {
listenerList.add(clazz, listener);
} else {
log.error("The class '" + clazz.getName() + "' is not a CacheEventListener. Ignoring this listener.");
}
}
/**
* Returns the list of all CacheEventListeners.
* @return the CacheEventListener's list of the Cache
*/
public EventListenerList getCacheEventListenerList() {
return listenerList;
}
/**
* 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 {@link NeedsRefreshException}.
true if the entry is stale, false otherwise.
*/
protected boolean isStale(CacheEntry cacheEntry, int refreshPeriod, String cronExpiry) {
boolean result = cacheEntry.needsRefresh(refreshPeriod) || isFlushed(cacheEntry);
if ((!result) && (cronExpiry != null) && (cronExpiry.length() > 0)) {
try {
FastCronParser parser = new FastCronParser(cronExpiry);
result = result || parser.hasMoreRecentMatch(cacheEntry.getLastUpdate());
} catch (ParseException e) {
log.warn(e);
}
}
return result;
}
/**
* Get the updating cache entry from the update map. If one is not found,
* create a new one (with state {@link EntryUpdateState#NOT_YET_UPDATING})
* and add it to the map.
*
* @param key The cache key for this entry
*
* @return the CacheEntry that was found (or added to) the updatingEntries
* map.
*/
protected EntryUpdateState getUpdateState(String key) {
EntryUpdateState updateState;
synchronized (updateStates) {
// Try to find the matching state object in the updating entry map.
updateState = (EntryUpdateState) updateStates.get(key);
if (updateState == null) {
// It's not there so add it.
updateState = new EntryUpdateState();
updateStates.put(key, updateState);
} else {
//Otherwise indicate that we start using it to prevent its removal until all threads are done with it.
updateState.incrementUsageCounter();
}
}
return updateState;
}
/**
* releases the usage that was made of the specified EntryUpdateState. When this reaches zero, the entry is removed from the map.
* @param state the state to release the usage of
* @param key the associated key.
*/
protected void releaseUpdateState(EntryUpdateState state, String key) {
synchronized (updateStates) {
int usageCounter = state.decrementUsageCounter();
checkEntryStateUpdateUsage(key, state, usageCounter);
}
}
/**
* Completely clears the cache.
*/
protected void clear() {
cacheMap.clear();
}
/**
* 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 {@link #putInCache} method, so it is possible that no EntryUpdateState was hold
* when this method is called.
*
* @param key The cache key that is no longer being updated.
*/
protected void completeUpdate(String key) {
EntryUpdateState state;
synchronized (updateStates) {
state = (EntryUpdateState) updateStates.get(key);
if (state != null) {
synchronized (state) {
int usageCounter = state.completeUpdate();
state.notifyAll();
checkEntryStateUpdateUsage(key, state, usageCounter);
}
} else {
//If putInCache() was called directly (i.e. not as a result of a NeedRefreshException) then no EntryUpdateState would be found.
}
}
}
/**
* Completely removes a cache entry from the cache and its associated cache
* groups.
*
* @param key The key of the entry to remove.
*/
public void removeEntry(String key) {
removeEntry(key, null);
}
/**
* Completely removes a cache entry from the cache and its associated cache
* groups.
*
* @param key The key of the entry to remove.
* @param origin The origin of this remove request.
*/
protected void removeEntry(String key, String origin) {
CacheEntry cacheEntry = (CacheEntry) cacheMap.get(key);
cacheMap.remove(key);
if (listenerList.getListenerCount() > 0) {
CacheEntryEvent event = new CacheEntryEvent(this, cacheEntry, origin);
dispatchCacheEntryEvent(CacheEntryEventType.ENTRY_REMOVED, event);
}
}
/**
* Dispatch a cache entry event to all registered listeners.
*
* @param eventType The type of event (used to branch on the proper method)
* @param event The event that was fired
*/
private void dispatchCacheEntryEvent(CacheEntryEventType eventType, CacheEntryEvent event) {
// Guaranteed to return a non-null array
Object[] listeners = listenerList.getListenerList();
// Process the listeners last to first, notifying
// those that are interested in this event
for (int i = listeners.length - 2; i >= 0; i -= 2) {
if (listeners[i+1] instanceof CacheEntryEventListener) {
CacheEntryEventListener listener = (CacheEntryEventListener) listeners[i+1];
if (eventType.equals(CacheEntryEventType.ENTRY_ADDED)) {
listener.cacheEntryAdded(event);
} else if (eventType.equals(CacheEntryEventType.ENTRY_UPDATED)) {
listener.cacheEntryUpdated(event);
} else if (eventType.equals(CacheEntryEventType.ENTRY_FLUSHED)) {
listener.cacheEntryFlushed(event);
} else if (eventType.equals(CacheEntryEventType.ENTRY_REMOVED)) {
listener.cacheEntryRemoved(event);
}
}
}
}
/**
* Dispatch a cache group event to all registered listeners.
*
* @param eventType The type of event (this is used to branch to the correct method handler)
* @param group The cache group that the event applies to
* @param origin The origin of this event (optional)
*/
private void dispatchCacheGroupEvent(CacheEntryEventType eventType, String group, String origin) {
CacheGroupEvent event = new CacheGroupEvent(this, group, origin);
// Guaranteed to return a non-null array
Object[] listeners = listenerList.getListenerList();
// Process the listeners last to first, notifying
// those that are interested in this event
for (int i = listeners.length - 2; i >= 0; i -= 2) {
if (listeners[i+1] instanceof CacheEntryEventListener) {
CacheEntryEventListener listener = (CacheEntryEventListener) listeners[i + 1];
if (eventType.equals(CacheEntryEventType.GROUP_FLUSHED)) {
listener.cacheGroupFlushed(event);
}
}
}
}
/**
* Dispatch a cache map access event to all registered listeners.
*
* @param eventType The type of event
* @param entry The entry that was affected.
* @param origin The origin of this event (optional)
*/
private void dispatchCacheMapAccessEvent(CacheMapAccessEventType eventType, CacheEntry entry, String origin) {
CacheMapAccessEvent event = new CacheMapAccessEvent(eventType, entry, origin);
// Guaranteed to return a non-null array
Object[] listeners = listenerList.getListenerList();
// Process the listeners last to first, notifying
// those that are interested in this event
for (int i = listeners.length - 2; i >= 0; i -= 2) {
if (listeners[i+1] instanceof CacheMapAccessEventListener) {
CacheMapAccessEventListener listener = (CacheMapAccessEventListener) listeners[i + 1];
listener.accessed(event);
}
}
}
/**
* Dispatch a cache pattern event to all registered listeners.
*
* @param eventType The type of event (this is used to branch to the correct method handler)
* @param pattern The cache pattern that the event applies to
* @param origin The origin of this event (optional)
*/
private void dispatchCachePatternEvent(CacheEntryEventType eventType, String pattern, String origin) {
CachePatternEvent event = new CachePatternEvent(this, pattern, origin);
// Guaranteed to return a non-null array
Object[] listeners = listenerList.getListenerList();
// Process the listeners last to first, notifying
// those that are interested in this event
for (int i = listeners.length - 2; i >= 0; i -= 2) {
if (listeners[i+1] instanceof CacheEntryEventListener) {
if (eventType.equals(CacheEntryEventType.PATTERN_FLUSHED)) {
CacheEntryEventListener listener = (CacheEntryEventListener) listeners[i+1];
listener.cachePatternFlushed(event);
}
}
}
}
/**
* Dispatches a cache-wide event to all registered listeners.
*
* @param eventType The type of event (this is used to branch to the correct method handler)
* @param origin The origin of this event (optional)
*/
private void dispatchCachewideEvent(CachewideEventType eventType, Date date, String origin) {
CachewideEvent event = new CachewideEvent(this, date, origin);
// Guaranteed to return a non-null array
Object[] listeners = listenerList.getListenerList();
// Process the listeners last to first, notifying
// those that are interested in this event
for (int i = listeners.length - 2; i >= 0; i -= 2) {
if (listeners[i+1] instanceof CacheEntryEventListener) {
if (eventType.equals(CachewideEventType.CACHE_FLUSHED)) {
CacheEntryEventListener listener = (CacheEntryEventListener) listeners[i+1];
listener.cacheFlushed(event);
}
}
}
}
/**
* Flush a cache entry. On completion of the flush, a
* CacheEntryEventType.ENTRY_FLUSHED event is fired.
*
* @param entry The entry to flush
* @param origin The origin of this flush event (optional)
*/
private void flushEntry(CacheEntry entry, String origin) {
String key = entry.getKey();
// Flush the object itself
entry.flush();
if (!entry.isNew()) {
// Update the entry's state in the map
cacheMap.put(key, entry);
}
// Trigger an ENTRY_FLUSHED event. [CACHE-107] Do this for all flushes.
if (listenerList.getListenerCount() > 0) {
CacheEntryEvent event = new CacheEntryEvent(this, entry, origin);
dispatchCacheEntryEvent(CacheEntryEventType.ENTRY_FLUSHED, event);
}
}
/**
* @return the total number of cache entries held in this cache.
*/
public int getSize() {
synchronized(cacheMap) {
return cacheMap.size();
}
}
/**
* Test support only: return the number of EntryUpdateState instances within the updateStates map.
*/
protected int getNbUpdateState() {
synchronized(updateStates) {
return updateStates.size();
}
}
/**
* Test support only: return the number of entries currently in the cache map
* @deprecated use getSize()
*/
public int getNbEntries() {
synchronized(cacheMap) {
return cacheMap.size();
}
}
}