/*
* This library is part of OpenCms -
* the Open Source Content Management System
*
* Copyright (c) Alkacon Software GmbH (http://www.alkacon.com)
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* For further information about Alkacon Software GmbH, please see the
* company website: http://www.alkacon.com
*
* For further information about OpenCms, please see the
* project website: http://www.opencms.org
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
package org.opencms.cache;
import org.opencms.main.CmsLog;
import org.apache.commons.logging.Log;
/**
* Implements an LRU (last recently used) cache.<p>
*
* The idea of this cache is to separate the caching policy from the data structure
* where the cached objects are stored. The advantage of doing so is, that the CmsFlexLruCache
* can identify the last-recently-used object in O(1), whereas you would need at least
* O(n) to traverse the data structure that stores the cached objects. Second, you can
* easily use the CmsFlexLruCache to get an LRU cache, no matter what data structure is used to
* store your objects.
* <p>
* The cache policy is affected by the "costs" of the objects being cached. Valuable cache costs
* might be the byte size of the cached objects for example.
* <p>
* To add/remove cached objects from the data structure that stores them, the objects have to
* implement the methods defined in the interface I_CmsLruCacheObject to be notified when they
* are added/removed from the CmsFlexLruCache.<p>
*
* @see org.opencms.cache.I_CmsLruCacheObject
*
* @since 6.0.0
*/
public class CmsLruCache extends java.lang.Object {
/** The log object for this class. */
private static final Log LOG = CmsLog.getLog(CmsLruCache.class);
/** The average sum of costs the cached objects. */
private long m_avgCacheCosts;
/** The head of the list of double linked LRU cache objects. */
private I_CmsLruCacheObject m_listHead;
/** The tail of the list of double linked LRU cache objects. */
private I_CmsLruCacheObject m_listTail;
/** The maximum sum of costs the cached objects might reach. */
private long m_maxCacheCosts;
/** The maximum costs of cacheable objects. */
private int m_maxObjectCosts;
/** The costs of all cached objects. */
private int m_objectCosts;
/** The sum of all cached objects. */
private int m_objectCount;
/**
* The constructor with all options.<p>
*
* @param theMaxCacheCosts the maximum cache costs of all cached objects
* @param theAvgCacheCosts the average cache costs of all cached objects
* @param theMaxObjectCosts the maximum allowed cache costs per object. Set theMaxObjectCosts to -1 if you don't want to limit the max. allowed cache costs per object
*/
public CmsLruCache(long theMaxCacheCosts, long theAvgCacheCosts, int theMaxObjectCosts) {
m_maxCacheCosts = theMaxCacheCosts;
m_avgCacheCosts = theAvgCacheCosts;
m_maxObjectCosts = theMaxObjectCosts;
}
/**
* Adds a new object to this cache.<p>
*
* If add the same object more than once,
* the object is touched instead.<p>
*
* @param theCacheObject the object being added to the cache
* @return true if the object was added to the cache, false if the object was denied because its cache costs were higher than the allowed max. cache costs per object
*/
public synchronized boolean add(I_CmsLruCacheObject theCacheObject) {
if (theCacheObject == null) {
// null can't be added or touched in the cache
return false;
}
// only objects with cache costs < the max. allowed object cache costs can be cached!
if ((m_maxObjectCosts != -1) && (theCacheObject.getLruCacheCosts() > m_maxObjectCosts)) {
if (LOG.isInfoEnabled()) {
LOG.info(Messages.get().getBundle().key(
Messages.LOG_CACHE_COSTS_TOO_HIGH_2,
new Integer(theCacheObject.getLruCacheCosts()),
new Integer(m_maxObjectCosts)));
}
return false;
}
if (!isCached(theCacheObject)) {
// add the object to the list of all cached objects in the cache
addHead(theCacheObject);
} else {
touch(theCacheObject);
}
// check if the cache has to trash the last-recently-used objects before adding a new object
if (m_objectCosts > m_maxCacheCosts) {
gc();
}
return true;
}
/**
* Removes all cached objects in this cache.<p>
*/
public synchronized void clear() {
// remove all objects from the linked list from the tail to the head:
I_CmsLruCacheObject currentObject = m_listTail;
while (currentObject != null) {
currentObject = currentObject.getNextLruObject();
removeTail();
}
// reset the data structure
m_objectCosts = 0;
m_objectCount = 0;
m_listHead = null;
m_listTail = null;
}
/**
* Returns the average costs of all cached objects.<p>
*
* @return the average costs of all cached objects
*/
public long getAvgCacheCosts() {
return m_avgCacheCosts;
}
/**
* Returns the max costs of all cached objects.<p>
*
* @return the max costs of all cached objects
*/
public long getMaxCacheCosts() {
return m_maxCacheCosts;
}
/**
* Returns the max allowed costs per cached object.<p>
*
* @return the max allowed costs per cached object
*/
public int getMaxObjectCosts() {
return m_maxObjectCosts;
}
/**
* Returns the current costs of all cached objects.<p>
*
* @return the current costs of all cached objects
*/
public int getObjectCosts() {
return m_objectCosts;
}
/**
* Removes an object from the list of all cached objects in this cache,
* no matter what position it has inside the list.<p>
*
* @param theCacheObject the object being removed from the list of all cached objects
* @return a reference to the object that was removed
*/
public synchronized I_CmsLruCacheObject remove(I_CmsLruCacheObject theCacheObject) {
if (!isCached(theCacheObject)) {
// theCacheObject is null or not inside the cache
return null;
}
// set the list pointers correct
if (theCacheObject.getNextLruObject() == null) {
// remove the object from the head pos.
I_CmsLruCacheObject newHead = theCacheObject.getPreviousLruObject();
if (newHead != null) {
// if newHead is null, theCacheObject
// was the only object in the cache
newHead.setNextLruObject(null);
}
m_listHead = newHead;
} else if (theCacheObject.getPreviousLruObject() == null) {
// remove the object from the tail pos.
I_CmsLruCacheObject newTail = theCacheObject.getNextLruObject();
if (newTail != null) {
// if newTail is null, theCacheObject
// was the only object in the cache
newTail.setPreviousLruObject(null);
}
m_listTail = newTail;
} else {
// remove the object from within the list
theCacheObject.getPreviousLruObject().setNextLruObject(theCacheObject.getNextLruObject());
theCacheObject.getNextLruObject().setPreviousLruObject(theCacheObject.getPreviousLruObject());
}
// update cache stats. and notify the cached object
decreaseCache(theCacheObject);
return theCacheObject;
}
/**
* Returns the count of all cached objects.<p>
*
* @return the count of all cached objects
*/
public int size() {
return m_objectCount;
}
/**
* Returns a string representing the current state of the cache.<p>
*
* @return a string representing the current state of the cache
*/
@Override
public String toString() {
StringBuffer buf = new StringBuffer();
buf.append("max. costs: " + m_maxCacheCosts).append(", ");
buf.append("avg. costs: " + m_avgCacheCosts).append(", ");
buf.append("max. costs/object: " + m_maxObjectCosts).append(", ");
buf.append("costs: " + m_objectCosts).append(", ");
buf.append("count: " + m_objectCount);
return buf.toString();
}
/**
* Touch an existing object in this cache, in the sense that it's "last-recently-used" state
* is updated.<p>
*
* @param theCacheObject the object being touched
* @return true if an object was found and touched
*/
public synchronized boolean touch(I_CmsLruCacheObject theCacheObject) {
if (!isCached(theCacheObject)) {
return false;
}
// only objects with cache costs < the max. allowed object cache costs can be cached!
if ((m_maxObjectCosts != -1) && (theCacheObject.getLruCacheCosts() > m_maxObjectCosts)) {
if (LOG.isInfoEnabled()) {
LOG.info(Messages.get().getBundle().key(
Messages.LOG_CACHE_COSTS_TOO_HIGH_2,
new Integer(theCacheObject.getLruCacheCosts()),
new Integer(m_maxObjectCosts)));
}
remove(theCacheObject);
return false;
}
// set the list pointers correct
I_CmsLruCacheObject nextObj = theCacheObject.getNextLruObject();
if (nextObj == null) {
// case 1: the object is already at the head pos.
return true;
}
I_CmsLruCacheObject prevObj = theCacheObject.getPreviousLruObject();
if (prevObj == null) {
// case 2: the object at the tail pos., remove it from the tail to put it to the front as the new head
I_CmsLruCacheObject newTail = nextObj;
newTail.setPreviousLruObject(null);
m_listTail = newTail;
} else {
// case 3: the object is somewhere within the list, remove it to put it the front as the new head
prevObj.setNextLruObject(nextObj);
nextObj.setPreviousLruObject(prevObj);
}
// set the touched object as the new head in the linked list:
I_CmsLruCacheObject oldHead = m_listHead;
if (oldHead != null) {
oldHead.setNextLruObject(theCacheObject);
theCacheObject.setNextLruObject(null);
theCacheObject.setPreviousLruObject(oldHead);
}
m_listHead = theCacheObject;
return true;
}
/**
* Adds a cache object as the new haed to the list of all cached objects in this cache.<p>
*
* @param theCacheObject the object being added as the new head to the list of all cached objects
*/
private void addHead(I_CmsLruCacheObject theCacheObject) {
// set the list pointers correct
if (m_objectCount > 0) {
// there is at least 1 object already in the list
I_CmsLruCacheObject oldHead = m_listHead;
oldHead.setNextLruObject(theCacheObject);
theCacheObject.setPreviousLruObject(oldHead);
m_listHead = theCacheObject;
} else {
// it is the first object to be added to the list
m_listTail = theCacheObject;
m_listHead = theCacheObject;
theCacheObject.setPreviousLruObject(null);
}
theCacheObject.setNextLruObject(null);
// update cache stats. and notify the cached object
increaseCache(theCacheObject);
}
/**
* Decrease this caches statistics
* and notify the cached object that it was removed from this cache.<p>
*
* @param theCacheObject the object being notified that it was removed from the cache
*/
private void decreaseCache(I_CmsLruCacheObject theCacheObject) {
// notify the object that it was now removed from the cache
//theCacheObject.notify();
theCacheObject.removeFromLruCache();
// set the list pointers to null
theCacheObject.setNextLruObject(null);
theCacheObject.setPreviousLruObject(null);
// update the cache stats.
m_objectCosts -= theCacheObject.getLruCacheCosts();
m_objectCount--;
}
/**
* Removes the last recently used objects from the list of all cached objects as long
* as the costs of all cached objects are higher than the allowed avg. costs of the cache.<p>
*/
private void gc() {
I_CmsLruCacheObject currentObject = m_listTail;
while (currentObject != null) {
if (m_objectCosts < m_avgCacheCosts) {
break;
}
currentObject = currentObject.getNextLruObject();
removeTail();
}
}
/**
* Increase this caches statistics
* and notify the cached object that it was added to this cache.<p>
*
* @param theCacheObject the object being notified that it was added to the cache
*/
private void increaseCache(I_CmsLruCacheObject theCacheObject) {
// notify the object that it was now added to the cache
//theCacheObject.notify();
theCacheObject.addToLruCache();
// update the cache stats.
m_objectCosts += theCacheObject.getLruCacheCosts();
m_objectCount++;
}
/**
* Test if a given object resides inside the cache.<p>
*
* @param theCacheObject the object to test
* @return true if the object is inside the cache, false otherwise
*/
private boolean isCached(I_CmsLruCacheObject theCacheObject) {
if ((theCacheObject == null) || (m_objectCount == 0)) {
// the cache is empty or the object is null (which is never cached)
return false;
}
I_CmsLruCacheObject nextObj = theCacheObject.getNextLruObject();
I_CmsLruCacheObject prevObj = theCacheObject.getPreviousLruObject();
if ((nextObj != null) || (prevObj != null)) {
// the object has either a predecessor or successor in the linked
// list of all cached objects, so it is inside the cache
return true;
}
// both nextObj and preObj are null
if ((m_objectCount == 1)
&& (m_listHead != null)
&& (m_listTail != null)
&& m_listHead.equals(theCacheObject)
&& m_listTail.equals(theCacheObject)) {
// the object is the one and only object in the cache
return true;
}
return false;
}
/**
* Removes the tailing object from the list of all cached objects.<p>
*/
private synchronized void removeTail() {
I_CmsLruCacheObject oldTail = m_listTail;
if (oldTail != null) {
I_CmsLruCacheObject newTail = oldTail.getNextLruObject();
// set the list pointers correct
if (newTail != null) {
// there are still objects remaining in the list
newTail.setPreviousLruObject(null);
m_listTail = newTail;
} else {
// we removed the last object from the list
m_listTail = null;
m_listHead = null;
}
// update cache stats. and notify the cached object
decreaseCache(oldTail);
}
}
}