cmsflexlrucache.java

内容管理

/*
 * File   : $Source: /usr/local/cvs/opencms/src/com/opencms/flex/util/Attic/CmsFlexLruCache.java,v $
 * Date   : $Date: 2003/02/26 15:19:23 $
 * Version: $Revision: 1.13 $
 *
 * This library is part of OpenCms -
 * the Open Source Content Mananagement System
 *
 * Copyright (C) 2002 - 2003 Alkacon Software (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, 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 com.opencms.flex.util;

import com.opencms.boot.I_CmsLogChannels;
import com.opencms.core.A_OpenCms;

/**
 * Implements an LRU (last recently used) cache.<p>
 * 
 * The idea of this cache 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_CmsFlexLruCacheObject to be notified when they
 * are added/removed from the CmsFlexLruCache.
 *
 * @see com.opencms.flex.util.I_CmsFlexLruCacheObject
 * @author Thomas Weckert ([e-mail])
 * @version $Revision: 1.13 $
 */
public class CmsFlexLruCache extends java.lang.Object {
    
    /** The head of the list of double linked LRU cache objects. */
    private I_CmsFlexLruCacheObject m_ListHead;
    
    /** The tail of the list of double linked LRU cache objects. */
    private I_CmsFlexLruCacheObject m_ListTail;
    
    /** Force a finalization after down-sizing the cache? */
    private boolean m_ForceFinalization;
    
    /** The max. sum of costs the cached objects might reach. */
    private int m_MaxCacheCosts;
    
    /** The avg. sum of costs the cached objects. */
    private int m_AvgCacheCosts;
    
    /** The max. 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 max. cache costs of all cached objects
     * @param theAvgCacheCosts the avg. cache costs of all cached objects
     * @param theMaxObjectCosts the max. allowed cache costs per object. Set theMaxObjectCosts to -1 if you don't want to limit the max. allowed cache costs per object
     * @param forceFinalization should be true if a system wide garbage collection/finalization is forced after objects were removed from the cache
     */
    public CmsFlexLruCache( int theMaxCacheCosts, int theAvgCacheCosts, int theMaxObjectCosts, boolean forceFinalization ) {
        this.m_ForceFinalization = forceFinalization;
        this.m_MaxCacheCosts = theMaxCacheCosts;
        this.m_AvgCacheCosts = theAvgCacheCosts;
        this.m_MaxObjectCosts = theMaxObjectCosts;
        
        this.m_ObjectCosts = this.m_ObjectCount = 0;
        this.m_ListHead = this.m_ListTail = null;
    }
    
    /**
     * Constructor for a LRU cache with forced garbage collection/finalization.<p>
     *
     * @param theMaxCacheCosts the max. cache costs of all cached objects
     * @param theAvgCacheCosts the avg. cache costs of all cached objects
     * @param theMaxObjectCosts the max. allowed cache costs per object. Set theMaxObjectCosts to -1 if you don't want to limit the max. allowed cache costs per object
     */
    public CmsFlexLruCache( int theMaxCacheCosts, int theAvgCacheCosts, int theMaxObjectCosts ) {
        this( theMaxCacheCosts, theAvgCacheCosts, theMaxObjectCosts, false );
    }
    
    /**
     * Constructor for a LRU cache with forced garbage collection/finalization, the max. allowed costs of cacheable
     * objects is 1/4 of the max. costs of all cached objects.<p>
     *
     * @param theMaxCacheCosts the max. cache costs of all cached objects
     * @param theAvgCacheCosts the avg. cache costs of all cached objects
     */
    public CmsFlexLruCache( int theMaxCacheCosts, int theAvgCacheCosts ) {
        this( theMaxCacheCosts, theAvgCacheCosts, theMaxCacheCosts/4, false );
    }
    
    /**
     * Constructor for a LRU cache where the max. allowed costs of cacheable objects is 1/4 of the max. costs of all cached objects.<p>
     *
     * @param theMaxCacheCosts the max. cache costs of all cached objects
     * @param theAvgCacheCosts the avg. cache costs of all cached objects
     * @param forceFinalization should be true if a system wide garbage collection/finalization is forced after objects were removed from the cache
     */
    public CmsFlexLruCache( int theMaxCacheCosts, int theAvgCacheCosts, boolean forceFinalization ) {
        this( theMaxCacheCosts, theAvgCacheCosts, theMaxCacheCosts/4, forceFinalization );
    }
    
    /**
     * Returns a string representing the current state of the cache.<p>
     */
    public String toString() {
        String objectInfo = "\n";
        
        objectInfo += "max. cache costs of all cached objects: " + this.m_MaxCacheCosts + "\n";
        objectInfo += "avg. cache costs of all cached objects: " + this.m_AvgCacheCosts + "\n";
        objectInfo += "max. cache costs per object: " + this.m_MaxObjectCosts + "\n";
        objectInfo += "costs of all cached objects: " + this.m_ObjectCosts + "\n";
        objectInfo += "sum of all cached objects: " + this.m_ObjectCount + "\n";
        
        if (!this.m_ForceFinalization) {
            objectInfo += "no ";
        }
        objectInfo += "system garbage collection is forced during clean up\n";
        
        return objectInfo;
    }
    
    /**
     * 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_CmsFlexLruCacheObject 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 ( (this.m_MaxObjectCosts!=-1) && (theCacheObject.getLruCacheCosts()>this.m_MaxObjectCosts) ) {
            if (I_CmsLogChannels.C_LOGGING && A_OpenCms.isLogging(I_CmsLogChannels.C_FLEX_CACHE))
                A_OpenCms.log(I_CmsLogChannels.C_FLEX_CACHE, "[FlexLruCache] you are trying to cache objects with cache costs " + theCacheObject.getLruCacheCosts() + " which is bigger than the max. allowed costs " + this.m_MaxObjectCosts );
            return false;
        }
        
        if (!this.isCached(theCacheObject)) {
            // add the object to the list of all cached objects in the cache
            this.addHead( theCacheObject );
        }
        else {
            this.touch( theCacheObject );
        }
        
        // check if the cache has to trash the last-recently-used objects before adding a new object
        if (this.m_ObjectCosts>this.m_MaxCacheCosts) {
            this.gc();
        }
        
        return true;
    }
    
    /**
     * Test if a given object resides inside the cache.<p>
     * 
     * @return true if the object is inside the cache, false otherwise
     */
    private boolean isCached( I_CmsFlexLruCacheObject theCacheObject ) {
        if (theCacheObject==null || this.m_ObjectCount==0) {
            // the cache is empty or the object is null (which is never cached)
            return false;
        }
        
        if (theCacheObject.getNextLruObject()!=null || theCacheObject.getPreviousLruObject()!=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;
        }
        
        if (theCacheObject.getNextLruObject()==null && theCacheObject.getPreviousLruObject()==null) {
            if (this.m_ObjectCount==1 && this.m_ListHead!=null && this.m_ListTail!=null && this.m_ListHead.equals(theCacheObject) && this.m_ListTail.equals(theCacheObject)) {
                // the object is the one and only object in the cache
                return true;
            }
        }
        
        return false;
    }
    
    /**
     * 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
     */
    public synchronized boolean touch( I_CmsFlexLruCacheObject theCacheObject ) {
        if (!this.isCached(theCacheObject)) return false;
        
        // only objects with cache costs < the max. allowed object cache costs can be cached!
        if ( (this.m_MaxObjectCosts!=-1) && (theCacheObject.getLruCacheCosts()>this.m_MaxObjectCosts) ) {
            if (I_CmsLogChannels.C_LOGGING && A_OpenCms.isLogging(I_CmsLogChannels.C_FLEX_CACHE))
                A_OpenCms.log(I_CmsLogChannels.C_FLEX_CACHE, "[FlexLruCache] you are trying to cache objects with cache costs " + theCacheObject.getLruCacheCosts() + " which is bigger than the max. allowed costs " + this.m_MaxObjectCosts );
            this.remove( theCacheObject );
            return false;
        }
                
        // set the list pointers correct
        if (theCacheObject.getNextLruObject()==null) {
            // case 1: the object is already at the head pos.
            return true;
        }
        else if (theCacheObject.getPreviousLruObject()==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_CmsFlexLruCacheObject newTail = theCacheObject.getNextLruObject();
            newTail.setPreviousLruObject( null );
            this.m_ListTail = newTail;
        }