/*

  * 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.algorithm.LRUCache;

 import com.opensymphony.oscache.base.algorithm.UnlimitedCache;

 import com.opensymphony.oscache.base.events.*;

 import com.opensymphony.oscache.base.persistence.PersistenceListener;

 import com.opensymphony.oscache.util.FastCronParser;

 import org.apache.commons.logging.Log;

 import org.apache.commons.logging.LogFactory;

 import java.io.Serializable;

 import java.text.ParseException;

 import java.util.*;

 import javax.swing.event.EventListenerList;

 /**

  * Provides an interface to the cache itself. Creating an instance of this class

  * will create a cache that behaves according to its construction parameters.

  * The public API provides methods to manage objects in the cache and configure

  * any cache event listeners.

  *

  * @version        $Revision: 1.1 $

  * @author <a href="mailto:mike@atlassian.com">Mike Cannon-Brookes</a>

  * @author <a href="mailto:tgochenour@peregrine.com">Todd Gochenour</a>

  * @author <a href="mailto:fbeauregard@pyxis-tech.com">Francois Beauregard</a>

  * @author <a href="&#109;a&#105;&#108;&#116;&#111;:chris&#64;swebtec.&#99;&#111;&#109;">Chris Miller</a>

  */

     /**

      * An event that origininated from within another event.

      */

     public static final String NESTED_EVENT = "NESTED";

     private static transient final Log log = LogFactory.getLog(Cache.class);

     /**

      * A list of all registered event listeners for this cache.

      */

     protected EventListenerList listenerList = new EventListenerList();

     /**

      * The actual cache map. This is where the cached objects are held.

      */

     private AbstractConcurrentReadCache cacheMap = null;

     /**

      * Date of last complete cache flush.

      */

     private Date flushDateTime = null;

     /**

      * A set that holds keys of cache entries that are currently being built.

      * The cache checks against this map when a stale entry is requested.

      * If the requested key is in here, we know the entry is currently being

      * built by another thread and hence we can either block and wait or serve

      * the stale entry (depending on whether cache blocking is enabled or not).

      * <p>

      * We need to isolate these here since the actual CacheEntry

      * objects may not normally be held in memory at all (eg, if 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

      */

     }

     /**

      * 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 (<code>blocking == true</code>) or

      * instead receive a copy of the stale content so they don't have to wait

      * (<code>blocking == false</code>). the default is <code>false</code>,

      * 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

      */

         // Instantiate the algo class if valid

             } catch (Exception e) {

             }

         }

             // If we have a capacity, use LRU cache otherwise use unlimited Cache

             } else {

             }

         }

     }

     /**

      * 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.

      */

     }

     /**

      * 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.

      */

         } else {

         }

     }

     /**

      * 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 <em>must</em> instead call

      * {@link #cancelUpdate(String)}.

      */

     }

     /**

      * 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 <em>must</em> instead call

      * {@link #cancelUpdate(String)}.

      */

     }

     /**

      * 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 <em>must</em> instead call

      * {@link #cancelUpdate(String)}.

      */

         // 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

                     // No one else is currently updating this entry - grab ownership

                     } else {

                     }

                     // 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.

                             } catch (InterruptedException e) {

                             }

                             // The updating thread cancelled the update, let this one have a go.

                             // We put the updateState object back into the updateStates map so

                             // any remaining threads waiting on this cache entry will be notified

                             // once this thread has done its thing (either updated the cache or

                             // cancelled the update). Without this code they'll get left hanging...

                             }

                             } else {

                             }

                         } else {

                         }

                     }

                 } else {

                 }

             }

         }

         // If reload is true then another thread must have successfully rebuilt the cache entry

             } else {

             }

         }

         // If we didn't end up getting a hit then we need to throw a NRE

         }

     }

     /**

      * Set the listener to use for data persistence. Only one

      * <code>PersistenceListener</code> can be configured per cache.

      *

      * @param listener The implementation of a persistance listener

      */

     }

     /**

      * Retrieves the currently configured <code>PersistenceListener</code>.

      *

      * @return the cache's <code>PersistenceListener</code>, or <code>null</code>

      * if no listener is configured.

      */

     }

     /**

      * 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.

      */

         } else {

         }

     }

     /**

      * Cancels any pending update for this cache entry. This should <em>only</em>

      * be called by the thread that is responsible for performing the update ie

      * the thread that received the original {@link NeedsRefreshException}.<p/>

      * If a cache entry is not updated (via {@link #putInCache} and this method is

      * not called to let OSCache know the update will not be forthcoming, subsequent

      * requests for this cache entry will either block indefinitely (if this is a new

      * cache entry or cache.blocking=true), or forever get served stale content. Note

      * however that there is no harm in cancelling an update on a key that either

      * does not exist or is not currently being updated.

      *

      * @param key The key for the cache entry in question.

      */

                     }

                 }

             }

         }

     }

     /**

      * Flush all entries in the cache on the given date/time.

      *

      * @param date The date at which all cache entries will be flushed.

      */

     }

     /**

      * Flush all entries in the cache on the given date/time.

      *

      * @param date The date at which all cache entries will be flushed.

      * @param origin The origin of this flush request (optional)

      */

         }

     }

     /**

      * Flush the cache entry (if any) that corresponds to the cache key supplied.

      * This call will flush the entry from the cache and remove the references to

      * it from any cache groups that it is a member of. On completion of the flush,

      * a <tt>CacheEntryEventType.ENTRY_FLUSHED</tt> event is fired.

      *

      * @param key The key of the entry to flush

      */

     }

     /**

      * Flush the cache entry (if any) that corresponds to the cache key supplied.

      * This call will mark the cache entry as flushed so that the next access

      * to it will cause a {@link NeedsRefreshException}. On completion of the

      * flush, a <tt>CacheEntryEventType.ENTRY_FLUSHED</tt> event is fired.

      *

      * @param key The key of the entry to flush

      * @param origin The origin of this flush request (optional)

      */

     }

     /**

      * Flushes all objects that belong to the supplied group. On completion

      * this method fires a <tt>CacheEntryEventType.GROUP_FLUSHED</tt> event.

      *

      * @param group The group to flush

      */

     }

     /**

      * Flushes all unexpired objects that belong to the supplied group. On

      * completion this method fires a <tt>CacheEntryEventType.GROUP_FLUSHED</tt>

      * event.

      *

      * @param group The group to flush

      * @param origin The origin of this flush event (optional)

      */

         // Flush all objects in the group

                 }

             }

         }

         }

     }

     /**

      * Flush all entries with keys that match a given pattern

      *

      * @param  pattern The key must contain this given value

      * @deprecated For performance and flexibility reasons it is preferable to

      * store cache entries in groups and use the {@link #flushGroup(String)} method

      * instead of relying on pattern flushing.

      */

     }

     /**

      * Flush all entries with keys that match a given pattern

      *

      * @param  pattern The key must contain this given value

      * @param origin The origin of this flush request

      * @deprecated For performance and flexibility reasons it is preferable to

      * store cache entries in groups and use the {@link #flushGroup(String, String)}

      * method instead of relying on pattern flushing.

      */

         // Check the pattern

                     }

                 }

             }

             }

         } else {

             // Empty pattern, nothing to do

         }

     }

     /**

      * Put an object in the cache specifying the key to use.

      *

      * @param key       Key of the object in the cache.

      * @param content   The object to cache.

      */

     }

     /**

      * Put an object in the cache specifying the key and refresh policy to use.

      *

      * @param key       Key of the object in the cache.

      * @param content   The object to cache.

      * @param policy   Object that implements refresh policy logic

      */

     }

     /**

      * Put in object into the cache, specifying both the key to use and the

      * cache groups the object belongs to.

      *

      * @param key       Key of the object in the cache

      * @param content   The object to cache

      * @param groups    The cache groups to add the object to

      */

     }

     /**

      * Put an object into the cache specifying both the key to use and the

      * cache groups the object belongs to.

      *

      * @param key       Key of the object in the cache

      * @param groups    The cache groups to add the object to

      * @param content   The object to cache

      * @param policy    Object that implements the refresh policy logic

      */

         // [CACHE-118] If we have an existing entry, create a new CacheEntry so we can still access the old one later

         }

         // Signal to any threads waiting on this update that it's now ready for them

         // in the cache!

             } else {

             }

         }

     }

     /**

      * Unregister a listener for Cache events.

      *

      * @param listener  The object that currently listens to events.

      */

     }

     /**

      * Get an entry from this cache or create one if it doesn't exist.

      *

      * @param key    The key of the cache entry

      * @param policy Object that implements refresh policy logic

      * @param origin The origin of request (optional)

      * @return CacheEntry for the specified key.

      */

         // Verify that the key is valid

         }

         // if the cache entry does not exist, create a new one

             }

         }

     }

     /**

      * Indicates whether or not the cache entry is stale.

      *

      * @param cacheEntry     The cache entry to test the freshness of.

      * @param refreshPeriod  The maximum allowable age of the entry, in seconds.

      * @param cronExpiry     A cron expression specifying absolute date(s) and/or time(s)

      * that the cache entry should expire at. If the cache entry was refreshed prior to

      * the most recent match for the cron expression, the entry will be considered stale.

      *

      * @return <code>true</code> if the entry is stale, <code>false</code> otherwise.

      */

             } catch (ParseException e) {

             }

         }

     }

     /**

      * 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.

      */

             // Try to find the matching state object in the updating entry map.

                 // It's not there so add it.

             }

         }

     }

     /**

      * Completely clears the cache.

      */

     }

     /**

      * 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.

      *

      * @param key The cache key that is no longer being updated.

      */

                 }

             }

         }

     }

     /**

      * Completely removes a cache entry from the cache and its associated cache

      * groups.

      *

      * @param key The key of the entry to remove.

      */

     }

     /**

      * 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.

      */

         }

     }

     /**

      * 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

      */

         // Guaranteed to return a non-null array

         // Process the listeners last to first, notifying

         // those that are interested in this 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)

      */

         // Guaranteed to return a non-null array

         // Process the listeners last to first, notifying

         // those that are interested in this 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)

      */

         // Guaranteed to return a non-null array

         // Process the listeners last to first, notifying

         // those that are interested in this 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)

      */

         // Guaranteed to return a non-null array

         // Process the listeners last to first, notifying

         // those that are interested in this 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)

      */

         // Guaranteed to return a non-null array

         // Process the listeners last to first, notifying

         // those that are interested in this event

                 }

             }

         }

     }

     /**

      * Flush a cache entry. On completion of the flush, a

      * <tt>CacheEntryEventType.ENTRY_FLUSHED</tt> event is fired.

      *

      * @param entry The entry to flush

      * @param origin The origin of this flush event (optional)

      */

         // Flush the object itself

             // Update the entry's state in the map

         }

         // Trigger an ENTRY_FLUSHED event. [CACHE-107] Do this for all flushes.

         }

     }

 }