com.sun.appserv.util.cache
Class BaseCache

java.lang.Object
  com.sun.appserv.util.cache.BaseCache

All Implemented Interfaces:

Cache

Direct Known Subclasses:

LruCache, MultiLruCache

public class BaseCache
extends Object
implements Cache

BaseCache Generic in-memory, abstract cache

Nested Class Summary

protected static class

BaseCache.CacheItem default CacheItem class implementation

Field Summary

protected static ResourceBundle	_rb The resource bundle containing the localized message strings.
protected Object[]	bucketLocks
protected BaseCache.CacheItem[]	buckets
protected int	entryCount
protected ArrayList	listeners
protected int	maxBuckets
protected boolean[]	refreshFlags
protected int	threshold threshold for the cache; once the threshold is reached entries are removed to accomodate newer inserts

Constructor Summary

BaseCache()
default constructor for the basic cache

Method Summary

protected Object	_put(int hashCode, Object key, Object value, int size, boolean addValue) cache the given value at the specified key and return previous value
protected BaseCache.CacheItem	_remove(int hashCode, Object key, Object value) remove the item stored at the key.
protected BaseCache.CacheItem	_removeItem(BaseCache.CacheItem ritem) remove the item stored at the key.
void	add(Object key, Object value) add the given value to the cache at the specified key
void	add(Object key, Object value, int size) add the given value with specified size to the cache at specified key
void	addCacheListener(CacheListener listener) add the cache module listener
int	clear() clear all the entries from the cache.
void	clearStats() clear the stats
boolean	contains(Object key) check if the cache contains the item at the key
protected BaseCache.CacheItem	createItem(int hashCode, Object key, Object value, int size) create new item
protected void	decrementEntryCount()
void	destroy() Sets all references to null.
Enumeration	elements() get an Enumeration for the keys stored in the cache
protected boolean	eq(Object x, Object y) Check for equality of non-null reference x and possibly-null y.
Object	get(int hashCode, Object key) get the item stored at the given pre-computed hash code and the key.
Object	get(Object key) get the item stored at the key.
Iterator	getAll(Object key) get all the items stored at the key.
int	getEntryCount() get the number of entries in the cache
protected int	getIndex(int hashCode) get the index of the item in the cache
int	getIndex(Object key) get the index of the item given a key
Object	getStatByName(String key) get the desired statistic counter
Map	getStats() get the stats snapshot
protected void	handleOverflow() increase the threshold
protected int	hash(Object x) Returns a hash code for non-null Object x.
protected void	incrementAddCount()
protected void	incrementEntryCount() synchronized counter updates
protected void	incrementHitCount()
protected void	incrementMissCount()
protected void	incrementOverflowCount()
protected void	incrementRefreshCount()
protected void	incrementRemovalCount()
void	init(int maxEntries, float loadFactor, Properties props) initialize the cache
void	init(int maxEntries, Properties props) initialize the cache
boolean	isEmpty() is this cache empty?
protected boolean	isThresholdReached() has cache reached its threshold
protected void	itemAccessed(BaseCache.CacheItem item) this item is accessed
protected BaseCache.CacheItem	itemAdded(BaseCache.CacheItem item) this item is just added to the cache
protected void	itemRefreshed(BaseCache.CacheItem item, int oldSize) item value has been refreshed
protected void	itemRemoved(BaseCache.CacheItem item) item value has been removed from the cache
Iterator	keys() get an Iterator for the keys stored in the cache
protected Object	loadValue(Object key, int hashCode) Cannot find an item with the given key and hashCode
void	notifyRefresh(int index) notify threads waiting for a refresh on the object associated with the key
Object	put(Object key, Object value) /** cache the given value at the specified key and return previous value
Object	put(Object key, Object value, int size) cache the given value at the specified key and return previous value
Object	remove(int hashCode, Object key) remove the item stored at the key.
Object	remove(Object key) remove the item stored at the key.
Object	remove(Object key, Object value) remove the given value stored at the key; value-specific removals.
void	removeAll(Object key) remove all the item with the given key.
void	trimExpiredEntries(int maxCount) trim the expired entries from the cache.
protected void	trimItem(BaseCache.CacheItem item) trim the item from the cache and notify listeners
Iterator	values() get an Iterator for the values stored in the cache
boolean	waitRefresh(int index) wait for a refresh on the object associated with the key

Methods inherited from class java.lang.Object

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

Field Detail

_rb

protected static ResourceBundle _rb

The resource bundle containing the localized message strings.

entryCount

protected int entryCount

threshold

protected int threshold

threshold for the cache; once the threshold is reached entries are removed to accomodate newer inserts

maxBuckets

protected int maxBuckets

buckets

protected BaseCache.CacheItem[] buckets

bucketLocks

protected Object[] bucketLocks

refreshFlags

protected boolean[] refreshFlags

listeners

protected ArrayList listeners

Constructor Detail

BaseCache

public BaseCache()

default constructor for the basic cache

Method Detail

init

public void init(int maxEntries,
                 Properties props)
          throws Exception

initialize the cache

Specified by:

init in interface Cache

Parameters:

maxEntries - maximum number of entries expected in the cache

props - opaque list of properties for a given cache implementation

Throws:

a - generic Exception if the initialization failed

Exception

init

public void init(int maxEntries,
                 float loadFactor,
                 Properties props)

initialize the cache

Specified by:

init in interface Cache

Parameters:

maxEntries - maximum number of entries expected in the cache

loadFactor - the load factor

props - opaque list of properties for a given cache implementation

Throws:

a - generic Exception if the initialization failed

addCacheListener

public void addCacheListener(CacheListener listener)

add the cache module listener

Specified by:

addCacheListener in interface Cache

Parameters:

listener - CacheListener implementation

hash

protected int hash(Object x)

Returns a hash code for non-null Object x.

eq

protected boolean eq(Object x,
                     Object y)

Check for equality of non-null reference x and possibly-null y.

handleOverflow

protected void handleOverflow()

increase the threshold

itemAdded

protected BaseCache.CacheItem itemAdded(BaseCache.CacheItem item)

this item is just added to the cache

Parameters:

item - CacheItem that was created

Returns:

a overflow item; may be null Cache bucket is already synchronized by the caller Here, if cache is overflowing (i.e. reached threshold); this class simply makes the cache unbounded by raising the threshold. Subclasses are expected to provide a robust cache replacement algorithm. Subclasses should enhance this implemntation.

itemAccessed

protected void itemAccessed(BaseCache.CacheItem item)

this item is accessed

Parameters:

item - CacheItem accessed Cache bucket is already synchronized by the caller

itemRefreshed

protected void itemRefreshed(BaseCache.CacheItem item,
                             int oldSize)

item value has been refreshed

Parameters:

item - CacheItem that was refreshed

oldSize - size of the previous value that was refreshed Cache bucket is already synchronized by the caller

itemRemoved

protected void itemRemoved(BaseCache.CacheItem item)

item value has been removed from the cache

Parameters:

item - CacheItem that was just removed Cache bucket is already synchronized by the caller

loadValue

protected Object loadValue(Object key,
                           int hashCode)

Cannot find an item with the given key and hashCode

Parameters:

key - Object that is not found

hashCode - int its hashCode

createItem

protected BaseCache.CacheItem createItem(int hashCode,
                                         Object key,
                                         Object value,
                                         int size)

create new item

Parameters:

hashCode - for the entry

key - Object key

value - Object value

size - size in bytes of the item subclasses may override to provide their own CacheItem extensions e.g. one that permits persistence.

isThresholdReached

protected boolean isThresholdReached()

has cache reached its threshold

Returns:

true when the cache reached its threshold

getIndex

protected final int getIndex(int hashCode)

get the index of the item in the cache

Parameters:

hashCode - of the entry

Returns:

the index to be used in the cache

getIndex

public final int getIndex(Object key)

get the index of the item given a key

Specified by:

getIndex in interface Cache

Parameters:

key - of the entry

Returns:

the index to be used in the cache

get

public Object get(Object key)

get the item stored at the key.

Specified by:

get in interface Cache

Parameters:

key - lookup key

get

public Object get(int hashCode,
                  Object key)

get the item stored at the given pre-computed hash code and the key.

Parameters:

key - lookup key

contains

public boolean contains(Object key)

check if the cache contains the item at the key

Specified by:

contains in interface Cache

Parameters:

key - lookup key

getAll

public Iterator getAll(Object key)

get all the items stored at the key.

Specified by:

getAll in interface Cache

Parameters:

key - lookup key

keys

public Iterator keys()

get an Iterator for the keys stored in the cache

Specified by:

keys in interface Cache

elements

public Enumeration elements()

get an Enumeration for the keys stored in the cache

Specified by:

elements in interface Cache

values

public Iterator values()

get an Iterator for the values stored in the cache

Specified by:

values in interface Cache

put

public Object put(Object key,
                  Object value)

/** cache the given value at the specified key and return previous value

Specified by:

put in interface Cache

Parameters:

key - lookup key

object - item value to be stored

put

public Object put(Object key,
                  Object value,
                  int size)

cache the given value at the specified key and return previous value

Specified by:

put in interface Cache

Parameters:

key - lookup key

object - item value to be stored

size - in bytes of the value being cached

add

public void add(Object key,
                Object value)

add the given value to the cache at the specified key

Specified by:

add in interface Cache

Parameters:

key - lookup key

object - item value to be stored

add

public void add(Object key,
                Object value,
                int size)

add the given value with specified size to the cache at specified key

Specified by:

add in interface Cache

Parameters:

key - lookup key

object - item value to be stored

size - in bytes of the value being added This function is suitable for multi-valued keys.

_put

protected Object _put(int hashCode,
                      Object key,
                      Object value,
                      int size,
                      boolean addValue)

cache the given value at the specified key and return previous value

Parameters:

hashCode - previously computed hashCode for the key

key - lookup key

object - item value to be stored

size - in bytes of the value being cached

addValue - treate this operation to add (default is to replace)

remove

public Object remove(Object key)

remove the item stored at the key.

Specified by:

remove in interface Cache

Parameters:

key - lookup key

remove

public Object remove(int hashCode,
                     Object key)

remove the item stored at the key.

Parameters:

hashCode - a precomputed hashCode

key - lookup key

remove

public Object remove(Object key,
                     Object value)

remove the given value stored at the key; value-specific removals.

Specified by:

remove in interface Cache

Parameters:

key - lookup key

value - to match (for a multi-valued keys)

_remove

protected BaseCache.CacheItem _remove(int hashCode,
                                      Object key,
                                      Object value)

remove the item stored at the key.

Parameters:

hashCode - a precomputed hashCode

key - lookup key

value - of the item to be matched

_removeItem

protected BaseCache.CacheItem _removeItem(BaseCache.CacheItem ritem)

remove the item stored at the key.

Parameters:

item - CacheItem to be removed

Returns:

the item stored at the key; null if not found.

removeAll

public void removeAll(Object key)

remove all the item with the given key.

Specified by:

removeAll in interface Cache

Parameters:

key - lookup key

trimItem

protected void trimItem(BaseCache.CacheItem item)

trim the item from the cache and notify listeners

Parameters:

item - to be trimmed

waitRefresh

public boolean waitRefresh(int index)

wait for a refresh on the object associated with the key

Specified by:

waitRefresh in interface Cache

Parameters:

key - lookup key

notifyRefresh

public void notifyRefresh(int index)

notify threads waiting for a refresh on the object associated with the key

Specified by:

notifyRefresh in interface Cache

Parameters:

key - lookup key

clear

public int clear()

clear all the entries from the cache.

Specified by:

clear in interface Cache

trimExpiredEntries

public void trimExpiredEntries(int maxCount)

trim the expired entries from the cache.

Specified by:

trimExpiredEntries in interface Cache

Parameters:

maxCount - maximum number of invalid entries to trim specify Integer.MAX_VALUE to trim all timedout entries This call is to be scheduled by a thread managed by the container.

getEntryCount

public int getEntryCount()

get the number of entries in the cache

Specified by:

getEntryCount in interface Cache

Returns:

the number of entries the cache currently holds

isEmpty

public boolean isEmpty()

is this cache empty?

Specified by:

isEmpty in interface Cache

incrementEntryCount

protected final void incrementEntryCount()

synchronized counter updates

decrementEntryCount

protected final void decrementEntryCount()

incrementHitCount

protected final void incrementHitCount()

incrementMissCount

protected final void incrementMissCount()

incrementRemovalCount

protected final void incrementRemovalCount()

incrementRefreshCount

protected final void incrementRefreshCount()

incrementAddCount

protected final void incrementAddCount()

incrementOverflowCount

protected final void incrementOverflowCount()

getStatByName

public Object getStatByName(String key)

get the desired statistic counter

Specified by:

getStatByName in interface Cache

Parameters:

key - to corresponding stat

Returns:

an Object corresponding to the stat See also: Constant.java for the key

getStats

public Map getStats()

get the stats snapshot

Specified by:

getStats in interface Cache

Returns:

a Map of stats See also: Constant.java for the keys

destroy

public void destroy()

Sets all references to null. This method should be called at the end of this object's life cycle.

Specified by:

destroy in interface Cache

clearStats

public void clearStats()

clear the stats

Specified by:

clearStats in interface Cache