com.jcorporate.expresso.core.cache
Class CacheManager

java.lang.Object
  com.jcorporate.expresso.core.cache.CacheManager

public class CacheManager

extends Object

CacheManager.java

Copyright 1999-2002 Jcorporate Ltd.

Cache Manager is a general-purpose class to handle all different kinds of caches - it provides both "ordered" caches (stored as a Vector of objects) and "unordered" caches (stored as a Hashtable).

The amount of data cached can be expressed as a count of items in the specified list (e.g. cache only so many items) or limited by the amount of free memory available (e.g. don't go below 10% of available memory being free). In both cases, the cached items are removed from the cache according to how frequently they have been used (e.g. a least-frequently-used algorithm is used to drop items from the cache).

Since:

Expresso 1.0

Constructor Summary

CacheManager()
Default Constructor.

Method Summary

static void	addItem(String dataContext, String cacheName, Cacheable newItem) Adds a Cacheable item into the cache
static void	addItem(String dataContext, String cacheName, Cacheable newItem, long expiry) Adds an item to the cache named by parameter cacheName
static void	addListener(String listener, String listenTo) Specify a relationship between caches.
static void	checkMemory() Checks to make sure that there is enough memory available to use for more caches.
static void	clear(String dataContext) Removes all cache items for a particular data context
static void	clear(String dataContext, String cacheName) Clear's the named cache.
static boolean	clearLowestCache() Deprecated. The cache manager takes care of itself
static void	clearNoNotify(String dataContext) Clears all caches in this db context but doesn't notify any listeners
static void	clearNoNotify(String dataContext, String cacheName) Clear the named cache, but don't send the remote system notifications.
static Cache	createCache(String dataContext, String cacheName, boolean ordered) Creates a cache as specified by the parameters listed.
static Cache	createCache(String dataContext, String cacheName, boolean ordered, int maxSize) Creates a cache defined by whether the cache is to be ordered, it's name and it's maximum size.
static void	destroy() Destroys the CacheManager.
static void	displayStatus() Displays the cache status.
static boolean	existsCache(String dataContext, String cacheName) Checks to see if the cache already exists.
static Enumeration	getAllCacheNames() Deprecated. use getAllCacheNamesIterator instead
static Enumeration	getAllCacheNames(String dataContext) Deprecated. Use getAllCacheNamesIterator intstead
static Iterator	getAllCacheNamesIterator() Deprecated. CacheNames doesn't belong in Configuration!! Query CacheManager instead!
static Iterator	getAllCacheNamesIterator(String dataContext) Get the names of all of the Caches being held for a particular context
static CacheSystem	getCacheSystem(String dataContext) Retrieve the cache system appropriate for the data context
static CacheManager	getInstance() Singleton instantiation.
static Cacheable	getItem(String dataContext, String cacheName, String valueKey) Get a particular item in the cache
static int	getItemCount(String dataContext, String cacheName) Return a count of the number of items in a cache.
static Vector	getItems(String dataContext, String cacheName) Return all of the items in a cache.
static void	removeItem(String dataContext, String cacheName, Cacheable itemToRemove) Removes an item from the cache
static void	removeItemNoNotify(String dataContext, String cacheName, Cacheable itemToRemove) Removes an item out of the cache without notifying the cache listeners
static void	setItems(String dataContext, String cacheName, Vector itemList) Sets a cache to have the particular items specified in itemList.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CacheManager

public CacheManager()

Default Constructor. Should actually only really be called by getInstance(), and it will eventually become protected

Method Detail

getInstance

public static CacheManager getInstance()

Singleton instantiation. First step in migrating away from static methods.

Ideally call this and operate on the instance() instead of the static member variables.

Returns:

the instance of the CacheManager

getCacheSystem

public static final CacheSystem getCacheSystem(String dataContext)

Retrieve the cache system appropriate for the data context

Parameters:

dataContext - the data context to retrieve the cache system for

Returns:

Cache system or null in the Component system when caching is not enabled.

destroy

public static void destroy()

Destroys the CacheManager. clears all caches, closes all cache sync instances and all the other miscellaneous cleanup.

addItem

public static void addItem(String dataContext,
                           String cacheName,
                           Cacheable newItem)
                    throws CacheException

Adds a Cacheable item into the cache

Parameters:

dataContext - the data context that this item is to reside in.

cacheName - The name of the cache.

newItem - The new item to add to the cache

Throws:

CacheException - upon error inserting into the system

addItem

public static void addItem(String dataContext,
                           String cacheName,
                           Cacheable newItem,
                           long expiry)
                    throws CacheException

Adds an item to the cache named by parameter cacheName

Parameters:

dataContext - The data context that this cache is for

cacheName - The name of the cache to store the object in

newItem - The new item to add to the cache

expiry - The time in miliseconds that this cache item will expire

Throws:

CacheException - if there's an error inserting the item into the cache

addListener

public static void addListener(String listener,
                               String listenTo)

Specify a relationship between caches. Whenever an add clear or remove event is sent to the specified cache, the listener is cleared as well. Adding a listener implies the relationship between the caches for ALL db contexts.

Parameters:

listener - The classname of the listener

listenTo - The name of the cache to listen to.

checkMemory

public static void checkMemory()

Checks to make sure that there is enough memory available to use for more caches. If it there isn't enough free memory, then it attempts to clear out the least used cache.

Creation date: (9/7/00 2:44:05 PM)

clearLowestCache

public static boolean clearLowestCache()

Deprecated. The cache manager takes care of itself

Removed the least used Cache

Returns:

true if something was able to be removed false otherwise

clear

public static void clear(String dataContext)
                  throws CacheException

Removes all cache items for a particular data context

Parameters:

dataContext - The data context to clear all items for.

Throws:

CacheException - CacheException if there's an error clearing the cache

clearNoNotify

public static void clearNoNotify(String dataContext)

Clears all caches in this db context but doesn't notify any listeners

Parameters:

dataContext - The data context that this cache is mapped to

clear

public static void clear(String dataContext,
                         String cacheName)
                  throws CacheException

Clear's the named cache.

Parameters:

dataContext - The dbContext of the cache

cacheName - The name of the cache to clear

Throws:

CacheException - if there's an error clearing the cache.

clearNoNotify

public static void clearNoNotify(String dataContext,
                                 String cacheName)

Clear the named cache, but don't send the remote system notifications. This method actually removes the cache from the list of available caches

Parameters:

dataContext - The dbContext that the cache is attached to

cacheName - The name of the cache

createCache

public static Cache createCache(String dataContext,
                                String cacheName,
                                boolean ordered)
                         throws CacheException

Creates a cache as specified by the parameters listed. Creation date: (9/7/00 2:18:09 PM)

Parameters:

dataContext - java.lang.String The data context for your app

cacheName - java.lang.String the name of the cache

ordered - boolean true if you want an ordered cache such as for ValidValues

Returns:

the newly instantiated Cache

Throws:

CacheException

createCache

public static Cache createCache(String dataContext,
                                String cacheName,
                                boolean ordered,
                                int maxSize)
                         throws CacheException

Creates a cache defined by whether the cache is to be ordered, it's name and it's maximum size. Creation date: (9/7/00 2:18:09 PM)

Parameters:

dataContext - java.lang.String The dbcontext that this cache is for

cacheName - java.lang.String The name of the cache

ordered - boolean True if you wish for an ordered cache.

maxSize - The maximum size of the cache

Returns:

the newly instantiated cache

Throws:

CacheException

displayStatus

public static void displayStatus()

Displays the cache status. Currently this is only really used for debugging purposes. Creation date: (9/7/00 2:44:05 PM)

existsCache

public static boolean existsCache(String dataContext,
                                  String cacheName)

Checks to see if the cache already exists. One big note about this is that unless you already have a ReadLock, the cache may or may not exist once you go to put your data in the cache. Buyer beware.

Parameters:

dataContext - The dbContext that this cache is hooked to

cacheName - The name of the cache

Returns:

true if the named cache already exists in this data context

getAllCacheNames

public static Enumeration getAllCacheNames()

Deprecated. use getAllCacheNamesIterator instead

Returns:

java.util.Enumeration of all cache names stored

getAllCacheNamesIterator

public static Iterator getAllCacheNamesIterator()

Deprecated. CacheNames doesn't belong in Configuration!! Query CacheManager instead!

Return an iterator over a list of Strings that contain all the names of the caches stored in the system [For dbContext default]

Returns:

java.util.Iterator

getAllCacheNames

public static Enumeration getAllCacheNames(String dataContext)

Deprecated. Use getAllCacheNamesIterator intstead

Get the names of all of the Caches being held for a particular context.

Parameters:

dataContext - The dbContext to get all the cache names for.

Returns:

java.util.Enumeration

getAllCacheNamesIterator

public static Iterator getAllCacheNamesIterator(String dataContext)

Get the names of all of the Caches being held for a particular context

Parameters:

dataContext - The dbContext to get the cache names for.

Returns:

java.util.Iterator

getItem

public static Cacheable getItem(String dataContext,
                                String cacheName,
                                String valueKey)

Get a particular item in the cache

Parameters:

dataContext - The dbContext for this cache

cacheName - The name of the cache

valueKey - The particular item within the cache to get

Returns:

a Cacheable object or null if it doesn't exist in the cache

getItems

public static Vector getItems(String dataContext,
                              String cacheName)

Return all of the items in a cache. If the cache was created as an ordered cache, the items will be in the order they were added. If not, they will be in no particular order. If there is no such cache or no items, null will be returned.

Parameters:

dataContext - The dbcontext for this cache

cacheName - The name of the cache to retrieve

Returns:

java.util.Vector of Cacheable items

getItemCount

public static int getItemCount(String dataContext,
                               String cacheName)

Return a count of the number of items in a cache. Return 0 if there is no such item

Parameters:

dataContext - the dbContext to retrieve from.

cacheName - The name of the cache

Returns:

an item count or zero if the cache doesn't exist or is empty;

removeItem

public static void removeItem(String dataContext,
                              String cacheName,
                              Cacheable itemToRemove)
                       throws CacheException

Removes an item from the cache

Parameters:

dataContext - The data context for the cache

cacheName - The name of the cache

itemToRemove - the key of the item to remove

Throws:

CacheException

removeItemNoNotify

public static void removeItemNoNotify(String dataContext,
                                      String cacheName,
                                      Cacheable itemToRemove)
                               throws CacheException

Removes an item out of the cache without notifying the cache listeners

Parameters:

dataContext - The name of the data context

cacheName - The cache name

itemToRemove - the key in the cache that has been modified

Throws:

CacheException - Upon error removing the item from the cache

setItems

public static void setItems(String dataContext,
                            String cacheName,
                            Vector itemList)
                     throws CacheException

Sets a cache to have the particular items specified in itemList.

Parameters:

dataContext - The dbContext for the cache

cacheName - The name of the cache

itemList - The items to set into the cache

Throws:

CacheException - if there's an error setting the items.