## 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`

Copyright © 2007 Mort Bay Consulting. All Rights Reserved.