Java tutorial
/* * 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); } } }