BaseCache (Common Utilities 4.0 API)

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

Nested Classes
Modifier and Type Class and Description

static class BaseCache.CacheItem
default CacheItem class implementation

Nested Classes
Modifier and Type	Class and Description
`static class`	`BaseCache.CacheItem` default CacheItem class implementation

Field Summary

Fields
Modifier and Type	Field and Description
`protected Object[]`	`bucketLocks`
`protected BaseCache.CacheItem[]`	`buckets`
`protected int`	`entryCount`
`protected int`	`hitCount`
`protected ArrayList`	`listeners`
`protected int`	`maxBuckets`
`protected int`	`maxEntries`
`protected int`	`missCount`
`protected boolean[]`	`refreshFlags`
`protected int`	`removalCount`
`protected int`	`threshold` threshold for the cache; once the threshold is reached entries are removed to accomodate newer inserts

Constructor Summary

Constructors
Constructor and Description

BaseCache()
default constructor for the basic cache

Constructors
Constructor and Description
`BaseCache()` default constructor for the basic cache

Method Summary

Methods
Modifier and Type	Method and Description
`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
  - maxEntries
```
protected int maxEntries
```
  - entryCount
```
protected int entryCount
```
  - threshold
```
protected int threshold
```
    threshold for the cache; once the threshold is reached entries are removed to accomodate newer inserts
  - hitCount
```
protected int hitCount
```
  - missCount
```
protected int missCount
```
  - removalCount
```
protected int removalCount
```
  - 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

Class BaseCache

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

maxEntries

entryCount

threshold

hitCount

missCount

removalCount

maxBuckets

buckets

bucketLocks

refreshFlags

listeners

Constructor Detail

BaseCache

Method Detail

init

init

addCacheListener

hash

eq

handleOverflow

itemAdded

itemAccessed

itemRefreshed

itemRemoved

loadValue

createItem

isThresholdReached

getIndex

getIndex

get

get

contains

getAll

keys

elements

values

put

put

add

add

_put

remove

remove

remove

_remove

_removeItem

removeAll

trimItem

waitRefresh

notifyRefresh

clear

trimExpiredEntries

getEntryCount

isEmpty

incrementEntryCount

decrementEntryCount

incrementHitCount

incrementMissCount

incrementRemovalCount

incrementRefreshCount

incrementAddCount

incrementOverflowCount

getStatByName

getStats

destroy

clearStats