abstractcacheadministrator.java

oscache-2.4.1-full

/*
 * Copyright (c) 2002-2003 by OpenSymphony
 * All rights reserved.
 */
package com.opensymphony.oscache.base;

import com.opensymphony.oscache.base.algorithm.AbstractConcurrentReadCache;
import com.opensymphony.oscache.base.events.*;
import com.opensymphony.oscache.base.persistence.PersistenceListener;
import com.opensymphony.oscache.util.StringUtil;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import java.util.*;

import javax.swing.event.EventListenerList;

/**
 * An AbstractCacheAdministrator defines an abstract cache administrator, implementing all
 * the basic operations related to the configuration of a cache, including assigning
 * any configured event handlers to cache objects.<p>
 *
 * Extend this class to implement a custom cache administrator.
 *
 * @version        $Revision: 425 $
 * @author        a href="mailto:[e-mail]">Mike Cannon-Brookes</a>
 * @author <a href="mailto:[e-mail]">Francois Beauregard</a>
 * @author <a href="mailto:[e-mail]">Alain Bergevin</a>
 * @author <a href="mailto:[e-mail]">Fabian Crabus</a>
 * @author <a href="&#109;a&#105;&#108;&#116;&#111;:chris&#64;swebtec.&#99;&#111;&#109;">Chris Miller</a>
 */
public abstract class AbstractCacheAdministrator implements java.io.Serializable {
    private static transient final Log log = LogFactory.getLog(AbstractCacheAdministrator.class);

    /**
     * A boolean cache configuration property that indicates whether the cache
     * should cache objects in memory. Set this property to <code>false</code>
     * to disable in-memory caching.
     */
    public final static String CACHE_MEMORY_KEY = "cache.memory";

    /**
     * An integer cache configuration property that specifies the maximum number
     * of objects to hold in the cache. Setting this to a negative value will
     * disable the capacity functionality - there will be no limit to the number
     * of objects that are held in cache.
     */
    public final static String CACHE_CAPACITY_KEY = "cache.capacity";

    /**
     * A String cache configuration property that specifies the classname of
     * an alternate caching algorithm. This class must extend
     * {@link com.opensymphony.oscache.base.algorithm.AbstractConcurrentReadCache}
     * By default caches will use {@link com.opensymphony.oscache.base.algorithm.LRUCache} as
     * the default algorithm if the cache capacity is set to a postive value, or
     * {@link com.opensymphony.oscache.base.algorithm.UnlimitedCache} if the
     * capacity is negative (ie, disabled).
     */
    public final static String CACHE_ALGORITHM_KEY = "cache.algorithm";

    /**
     * A boolean cache configuration property that indicates whether the persistent
     * cache should be unlimited in size, or should be restricted to the same size
     * as the in-memory cache. Set this property to <code>true</code> to allow the
     * persistent cache to grow without bound.
     */
    public final static String CACHE_DISK_UNLIMITED_KEY = "cache.unlimited.disk";

    /**
     * The configuration key that specifies whether we should block waiting for new
     * content to be generated, or just serve the old content instead. The default
     * behaviour is to serve the old content since that provides the best performance
     * (at the cost of serving slightly stale data).
     */
    public final static String CACHE_BLOCKING_KEY = "cache.blocking";

    /**
     * A String cache configuration property that specifies the classname that will
     * be used to provide cache persistence. This class must extend {@link PersistenceListener}.
     */
    public static final String PERSISTENCE_CLASS_KEY = "cache.persistence.class";

    /**
     * A String cache configuration property that specifies if the cache persistence
     * will only be used in overflow mode, that is, when the memory cache capacity has been reached.
     */
    public static final String CACHE_PERSISTENCE_OVERFLOW_KEY = "cache.persistence.overflow.only";

    /**
     * A String cache configuration property that holds a comma-delimited list of
     * classnames. These classes specify the event handlers that are to be applied
     * to the cache.
     */
    public static final String CACHE_ENTRY_EVENT_LISTENERS_KEY = "cache.event.listeners";
    protected Config config = null;

    /**
     * Holds a list of all the registered event listeners. Event listeners are specified
     * using the {@link #CACHE_ENTRY_EVENT_LISTENERS_KEY} configuration key.
     */
    protected EventListenerList listenerList = new EventListenerList();

    /**
     * The algorithm class being used, as specified by the {@link #CACHE_ALGORITHM_KEY}
     * configuration property.
     */
    protected String algorithmClass = null;

    /**
     * The cache capacity (number of entries), as specified by the {@link #CACHE_CAPACITY_KEY}
     * configuration property.
     */
    protected int cacheCapacity = -1;

    /**
     * Whether the cache blocks waiting for content to be build, or serves stale
     * content instead. This value can be specified using the {@link #CACHE_BLOCKING_KEY}
     * configuration property.
     */
    private boolean blocking = false;

    /**
     * Whether or not to store the cache entries in memory. This is configurable using the
     * {@link com.opensymphony.oscache.base.AbstractCacheAdministrator#CACHE_MEMORY_KEY} property.
     */
    private boolean memoryCaching = true;

    /**
     * Whether the persistent cache should be used immediately or only when the memory capacity
         * has been reached, ie. overflow only.
     * This can be set via the {@link #CACHE_PERSISTENCE_OVERFLOW_KEY} configuration property.
     */
    private boolean overflowPersistence;

    /**
     * Whether the disk cache should be unlimited in size, or matched 1-1 to the memory cache.
     * This can be set via the {@link #CACHE_DISK_UNLIMITED_KEY} configuration property.
     */
    private boolean unlimitedDiskCache;

    /**
     * Create the AbstractCacheAdministrator.
     * This will initialize all values and load the properties from oscache.properties.
     */
    protected AbstractCacheAdministrator() {
        this(null);
    }

    /**
     * Create the AbstractCacheAdministrator.
     *
     * @param p the configuration properties for this cache.
     */
    protected AbstractCacheAdministrator(Properties p) {
        loadProps(p);
        initCacheParameters();

        if (log.isDebugEnabled()) {
            log.debug("Constructed AbstractCacheAdministrator()");
        }
    }

    /**
     * Sets the algorithm to use for the cache.
     *
     * @see com.opensymphony.oscache.base.algorithm.LRUCache
     * @see com.opensymphony.oscache.base.algorithm.FIFOCache
     * @see com.opensymphony.oscache.base.algorithm.UnlimitedCache
     * @param newAlgorithmClass The class to use (eg.
     * <code>"com.opensymphony.oscache.base.algorithm.LRUCache"</code>)
     */
    public void setAlgorithmClass(String newAlgorithmClass) {
        algorithmClass = newAlgorithmClass;
    }

    /**
     * Indicates whether the cache will block waiting for new content to
     * be built, or serve stale content instead of waiting. Regardless of this
     * setting, the cache will <em>always</em> block if new content is being
     * created, ie, there's no stale content in the cache that can be served.
     */
    public boolean isBlocking() {
        return blocking;
    }

    /**
     * Sets the cache capacity (number of items). Administrator implementations
     * should override this method to ensure that their {@link Cache} objects
     * are updated correctly (by calling {@link AbstractConcurrentReadCache#setMaxEntries(int)}}}.
     *
     * @param newCacheCapacity The new capacity
     */
    protected void setCacheCapacity(int newCacheCapacity) {
        cacheCapacity = newCacheCapacity;
    }

    /**
     * Whether entries are cached in memory or not.
     * Default is true.
     * Set by the <code>cache.memory</code> property.
     *
     * @return Status whether or not memory caching is used.
     */
    public boolean isMemoryCaching() {
        return memoryCaching;
    }