Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.opensymphony.oscache.base
Class Cache

    java.lang.Object
      com.opensymphony.oscache.base.Cache

All Implemented Interfaces:
  java.io.Serializable

Direct Known Subclasses:
  ServletCache

public class Cache
extends java.lang.Object
implements java.io.Serializable

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.6 $
Author:
  Mike Cannon-Brookes, Todd Gochenour, Francois Beauregard, Chris Miller
See Also:
  Serialized Form

Field Summary
`protected javax.swing.event.EventListenerList` | `listenerList` A list of all registered event listeners for this cache.
`static java.lang.String` | `NESTED_EVENT` An event that origininated from within another event.

Constructor Summary
`Cache(boolean useMemoryCaching, boolean unlimitedDiskCache)` Create a new Cache
`Cache(boolean useMemoryCaching, boolean unlimitedDiskCache, boolean blocking, java.lang.String algorithmClass, int capacity)` Create a new Cache.

Method Summary
`void` | `addCacheEventListener(CacheEventListener listener, java.lang.Class clazz)` Register a listener for Cache events.
`void` | `cancelUpdate(java.lang.String key)` Cancels any pending update for this cache entry.
`protected void` | `clear()` Completely clears the cache.
`protected void` | `completeUpdate(java.lang.String key)` Removes the update state for the specified key and notifies any other threads that are waiting on this object.
`void` | `flushAll(java.util.Date date)` Flush all entries in the cache on the given date/time.
`void` | `flushAll(java.util.Date date, java.lang.String origin)` Flush all entries in the cache on the given date/time.
`void` | `flushEntry(java.lang.String key)` Flush the cache entry (if any) that corresponds to the cache key supplied.
`void` | `flushEntry(java.lang.String key, java.lang.String origin)` Flush the cache entry (if any) that corresponds to the cache key supplied.
`void` | `flushGroup(java.lang.String group)` Flushes all objects that belong to the supplied group.
`void` | `flushGroup(java.lang.String group, java.lang.String origin)` Flushes all unexpired objects that belong to the supplied group.
`void` | `flushPattern(java.lang.String pattern)` Deprecated. For performance and flexibility reasons it is preferable to store cache entries in groups and use the `flushGroup(String)` method instead of relying on pattern flushing.
`void` | `flushPattern(java.lang.String pattern, java.lang.String origin)` Deprecated. For performance and flexibility reasons it is preferable to store cache entries in groups and use the `flushGroup(String, String)` method instead of relying on pattern flushing.
`protected CacheEntry` | `getCacheEntry(java.lang.String key, EntryRefreshPolicy policy, java.lang.String origin)` Get an entry from this cache or create one if it doesn't exist.
`java.lang.Object` | `getFromCache(java.lang.String key)` Retrieve an object from the cache specifying its key.
`java.lang.Object` | `getFromCache(java.lang.String key, int refreshPeriod)` Retrieve an object from the cache specifying its key.
`java.lang.Object` | `getFromCache(java.lang.String key, int refreshPeriod, java.lang.String cronExpiry)` Retrieve an object from the cache specifying its key.
`PersistenceListener` | `getPersistenceListener()` Retrieves the currently configured `PersistenceListener`.
`protected EntryUpdateState` | `getUpdateState(java.lang.String key)` Get the updating cache entry from the update map.
`boolean` | `isFlushed(CacheEntry cacheEntry)` Checks if the cache was flushed more recently than the CacheEntry provided.
`protected boolean` | `isStale(CacheEntry cacheEntry, int refreshPeriod, java.lang.String cronExpiry)` Indicates whether or not the cache entry is stale.
`void` | `putInCache(java.lang.String key, java.lang.Object content)` Put an object in the cache specifying the key to use.
`void` | `putInCache(java.lang.String key, java.lang.Object content, EntryRefreshPolicy policy)` Put an object in the cache specifying the key and refresh policy to use.
`void` | `putInCache(java.lang.String key, java.lang.Object content, java.lang.String[] groups)` Put in object into the cache, specifying both the key to use and the cache groups the object belongs to.
`void` | `putInCache(java.lang.String key, java.lang.Object content, java.lang.String[] groups, EntryRefreshPolicy policy, java.lang.String origin)` Put an object into the cache specifying both the key to use and the cache groups the object belongs to.
`void` | `removeCacheEventListener(CacheEventListener listener, java.lang.Class clazz)` Unregister a listener for Cache events.
`protected void` | `removeEntry(java.lang.String key)` Completely removes a cache entry from the cache and its associated cache groups.
`protected void` | `removeEntry(java.lang.String key, java.lang.String origin)` Completely removes a cache entry from the cache and its associated cache groups.
`void` | `setCapacity(int capacity)` Allows the capacity of the cache to be altered dynamically.
`void` | `setPersistenceListener(PersistenceListener listener)` Set the listener to use for data persistence.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### NESTED_EVENT

    public static final java.lang.String NESTED_EVENT

  An event that origininated from within another event.

  See Also:
    Constant Field Values

### listenerList

    protected javax.swing.event.EventListenerList listenerList

  A list of all registered event listeners for this cache.

Constructor Detail

### Cache

    public Cache(boolean useMemoryCaching,
                 boolean unlimitedDiskCache)

  Create a new Cache

Parameters:
  `useMemoryCaching` - Specify if the memory caching is going to be used
  `unlimitedDiskCache` - Specify if the disk caching is unlimited

### Cache

    public Cache(boolean useMemoryCaching,
                 boolean unlimitedDiskCache,
                 boolean blocking,
                 java.lang.String algorithmClass,
                 int capacity)

  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.

Parameters:
  `useMemoryCaching` - Specify if the memory caching is going to be used
  `unlimitedDiskCache` - Specify if the disk caching is unlimited
  `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 (`blocking == true`) or instead receive a copy of the stale content so they don't have to wait (`blocking == false`). the default is `false`, which provides better performance but at the expense of slightly stale data being served.
  `algorithmClass` - The class implementing the desired algorithm
  `capacity` - The capacity
See Also:
  `LRUCache`, `UnlimitedCache`

Method Detail

### setCapacity

    public void setCapacity(int capacity)

  Allows the capacity of the cache to be altered dynamically. Note that some cache implementations may choose to ignore this setting (eg the `UnlimitedCache` ignores this call).

  Parameters:
    `capacity` - the maximum number of items to hold in the cache.

### isFlushed

    public boolean isFlushed(CacheEntry cacheEntry)

  Checks if the cache was flushed more recently than the CacheEntry provided. Used to determine whether to refresh the particular CacheEntry.

  Parameters:
    `cacheEntry` - The cache entry which we're seeing whether to refresh
  Returns:
    Whether or not the cache has been flushed more recently than this cache entry was updated.

### getFromCache

    public java.lang.Object getFromCache(java.lang.String key)
                                  throws NeedsRefreshException

  Retrieve an object from the cache specifying its key.

  Parameters:
    `key` - Key of the object in the cache.
  Returns:
    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 must instead call `cancelUpdate(String)`.

### getFromCache

    public java.lang.Object getFromCache(java.lang.String key,
                                         int refreshPeriod)
                                  throws NeedsRefreshException

  Retrieve an object from the cache specifying its key.

  Parameters:
    `key` - Key of the object in the cache.
    `refreshPeriod` - How long before the object needs refresh. To allow the object to stay in the cache indefinitely, supply a value of `CacheEntry.INDEFINITE_EXPIRY`.
  Returns:
    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 must instead call `cancelUpdate(String)`.

### getFromCache

    public java.lang.Object getFromCache(java.lang.String key,
                                         int refreshPeriod,
                                         java.lang.String cronExpiry)
                                  throws NeedsRefreshException

  Retrieve an object from the cache specifying its key.

  Parameters:
    `key` - Key of the object in the cache.
    `refreshPeriod` - How long before the object needs refresh. To allow the object to stay in the cache indefinitely, supply a value of `CacheEntry.INDEFINITE_EXPIRY`.
    `cronExpiry` - A cron expression that specifies fixed date(s) and/or time(s) that this cache entry should expire on.
  Returns:
    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 must instead call `cancelUpdate(String)`.

### setPersistenceListener

    public void setPersistenceListener(PersistenceListener listener)

  Set the listener to use for data persistence. Only one `PersistenceListener` can be configured per cache.

  Parameters:
    `listener` - The implementation of a persistance listener

### getPersistenceListener

    public PersistenceListener getPersistenceListener()

  Retrieves the currently configured `PersistenceListener`.

  Returns:
    the cache's `PersistenceListener`, or `null` if no listener is configured.

### addCacheEventListener

    public void addCacheEventListener(CacheEventListener listener,
                                      java.lang.Class clazz)

  Register a listener for Cache events. The listener must implement one of the child interfaces of the `CacheEventListener` interface.

  Parameters:
    `listener` - The object that listens to events.

### cancelUpdate

    public void cancelUpdate(java.lang.String key)

  Cancels any pending update for this cache entry. This should only be called by the thread that is responsible for performing the update ie the thread that received the original `NeedsRefreshException`.

  If a cache entry is not updated (via `putInCache(java.lang.String, java.lang.Object)` 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.

  Parameters:
    `key` - The key for the cache entry in question.

### flushAll

    public void flushAll(java.util.Date date)

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

  Parameters:
    `date` - The date at which all cache entries will be flushed.

### flushAll

    public void flushAll(java.util.Date date,
                         java.lang.String origin)

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

  Parameters:
    `date` - The date at which all cache entries will be flushed.
    `origin` - The origin of this flush request (optional)

### flushEntry

    public void flushEntry(java.lang.String key)

  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 `CacheEntryEventType.ENTRY_FLUSHED` event is fired.

  Parameters:
    `key` - The key of the entry to flush

### flushEntry

    public void flushEntry(java.lang.String key,
                           java.lang.String origin)

  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 `NeedsRefreshException`. On completion of the flush, a `CacheEntryEventType.ENTRY_FLUSHED` event is fired.

  Parameters:
    `key` - The key of the entry to flush
    `origin` - The origin of this flush request (optional)

### flushGroup

    public void flushGroup(java.lang.String group)

  Flushes all objects that belong to the supplied group. On completion this method fires a `CacheEntryEventType.GROUP_FLUSHED` event.

  Parameters:
    `group` - The group to flush

### flushGroup

    public void flushGroup(java.lang.String group,
                           java.lang.String origin)

  Flushes all unexpired objects that belong to the supplied group. On completion this method fires a `CacheEntryEventType.GROUP_FLUSHED` event.

  Parameters:
    `group` - The group to flush
    `origin` - The origin of this flush event (optional)

### flushPattern

    public void flushPattern(java.lang.String pattern)

  Deprecated. For performance and flexibility reasons it is preferable to store cache entries in groups and use the `flushGroup(String)` method instead of relying on pattern flushing.

  Flush all entries with keys that match a given pattern

  Parameters:
    `pattern` - The key must contain this given value

### flushPattern

    public void flushPattern(java.lang.String pattern,
                             java.lang.String origin)

  Deprecated. For performance and flexibility reasons it is preferable to store cache entries in groups and use the `flushGroup(String, String)` method instead of relying on pattern flushing.

  Flush all entries with keys that match a given pattern

  Parameters:
    `pattern` - The key must contain this given value
    `origin` - The origin of this flush request

### putInCache

    public void putInCache(java.lang.String key,
                           java.lang.Object content)

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

  Parameters:
    `key` - Key of the object in the cache.
    `content` - The object to cache.

### putInCache

    public void putInCache(java.lang.String key,
                           java.lang.Object content,
                           EntryRefreshPolicy policy)

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

  Parameters:
    `key` - Key of the object in the cache.
    `content` - The object to cache.
    `policy` - Object that implements refresh policy logic

### putInCache

    public void putInCache(java.lang.String key,
                           java.lang.Object content,
                           java.lang.String[] groups)

  Put in object into the cache, specifying both the key to use and the cache groups the object belongs to.

  Parameters:
    `key` - Key of the object in the cache
    `content` - The object to cache
    `groups` - The cache groups to add the object to

### putInCache

    public void putInCache(java.lang.String key,
                           java.lang.Object content,
                           java.lang.String[] groups,
                           EntryRefreshPolicy policy,
                           java.lang.String origin)

  Put an object into the cache specifying both the key to use and the cache groups the object belongs to.

  Parameters:
    `key` - Key of the object in the cache
    `groups` - The cache groups to add the object to
    `content` - The object to cache
    `policy` - Object that implements the refresh policy logic

### removeCacheEventListener

    public void removeCacheEventListener(CacheEventListener listener,
                                         java.lang.Class clazz)

  Unregister a listener for Cache events.

  Parameters:
    `listener` - The object that currently listens to events.

### getCacheEntry

    protected CacheEntry getCacheEntry(java.lang.String key,
                                       EntryRefreshPolicy policy,
                                       java.lang.String origin)

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

  Parameters:
    `key` - The key of the cache entry
    `policy` - Object that implements refresh policy logic
    `origin` - The origin of request (optional)
  Returns:
    CacheEntry for the specified key.

### isStale

    protected boolean isStale(CacheEntry cacheEntry,
                              int refreshPeriod,
                              java.lang.String cronExpiry)

  Indicates whether or not the cache entry is stale.

  Parameters:
    `cacheEntry` - The cache entry to test the freshness of.
    `refreshPeriod` - The maximum allowable age of the entry, in seconds.
    `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.
  Returns:
    `true` if the entry is stale, `false` otherwise.

### getUpdateState

    protected EntryUpdateState getUpdateState(java.lang.String key)

  Get the updating cache entry from the update map. If one is not found, create a new one (with state `EntryUpdateState.NOT_YET_UPDATING`) and add it to the map.

  Parameters:
    `key` - The cache key for this entry
  Returns:
    the CacheEntry that was found (or added to) the updatingEntries map.

### clear

    protected void clear()

  Completely clears the cache.

### completeUpdate

    protected void completeUpdate(java.lang.String key)

  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 `putInCache(java.lang.String, java.lang.Object)` method.

  Parameters:
    `key` - The cache key that is no longer being updated.

### removeEntry

    protected void removeEntry(java.lang.String key)

  Completely removes a cache entry from the cache and its associated cache groups.

  Parameters:
    `key` - The key of the entry to remove.

### removeEntry

    protected void removeEntry(java.lang.String key,
                               java.lang.String origin)

  Completely removes a cache entry from the cache and its associated cache groups.

  Parameters:
    `key` - The key of the entry to remove.
    `origin` - The origin of this remove request.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| See www.opensymphony.com for more information.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD