AbstractHashbelt (Castor 1.3.2 API)

java.lang.Object
- org.castor.cache.AbstractBaseCache
- - org.castor.cache.hashbelt.AbstractHashbelt

All Implemented Interfaces:

Map<Object,Object>, Cache

Direct Known Subclasses:

FIFOHashbelt, LRUHashbelt
```
public abstract class AbstractHashbelt
extends AbstractBaseCache
```
An abstract, core implementation of the hashbelt functionality; individual implementations will differ on the underlying behavior.
A hashbelt has six important values which get set at initialization:

containers

The number of containers in the conveyor belt. For example: If a box will drop off of the conveyor belt every 30 seconds, and you want a cache that lasts for 5 minutes, you want 5 / 30 = 6 containers on the belt. Every 30 seconds, another, clean container goes on the front of the conveyor belt, and everything in the last belt gets discarded. If not specified 10 containers are used by default.
For systems with fine granularity, you are free to use a large number of containers; but the system is most efficient when the user decides on a "sweet spot" determining both the number of containers to be managed on the whole and the optimal number of buckets in those containers for managing. This is ultimately a performance/accuracy tradeoff with the actual discard-from-cache time being further from the mark as the rotation time goes up. Also the number of objects discarded at once when capacity limit is reached depends upon the number of containers.

capacity

Maximum capacity of the whole cache. If there are, for example, ten containers on the belt and the capacity has been set to 1000, each container will hold a maximum of 1000/10 objects. Therefore if the capacity limit is reached and the last container gets droped from the belt there are up to 100 objects discarted at once. By default the capacity is set to 0 which causes capacity limit to be ignored so the cache can hold an undefined number of objects.

ttl

The maximum time an object lifes in cache. If the are, for example, ten containers and ttl is set to 300 seconds (5 minutes), a new container will be put in front of the belt every 300/10 = 30 seconds while another is dropped at the end at the same time. Due to the granularity of 30 seconds, everything just until 5 minutes 30 seconds will also end up in this box. The default value for ttl is 60 seconds. If ttl is set to 0 which means that objects life in cache for unlimited time and may only discarded by a capacity limit.

monitor

The monitor intervall in minutes when hashbelt cache rports the current number of containers used and objects cached. If set to 0 (default) monitoring is disabled.

container-class

The implementation of org.castor.cache.hashbelt.container.Container interface to be used for all containers of the cache. Castor provides the following 3 implementations of the Container interface.
org.castor.cache.hashbelt.container.FastIteratingContainer
org.castor.cache.hashbelt.container.MapContainer
org.castor.cache.hashbelt.container.WeakReferenceContainer
If not specified the MapContainer will be used as default.

reaper-class

Specific reapers yield different behaviors. The GC reaper, the default, just dumps the contents to the garbage collector. However, custom implementations may want to actually do something when a bucket drops off the end; see the javadocs on other available reapers to find a reaper strategy that meets your behavior requirements. Apart of the default org.castor.cache.hashbelt.reaper.NullReaper we provide 3 abstract implementations of org.castor.cahe.hashbelt.reaper.Reaper interface:
org.castor.cache.hashbelt.reaper.NotifyingReaper
org.castor.cache.hashbelt.reaper.RefreshingReaper
org.castor.cache.hashbelt.reaper.ReinsertingReaper
to be extended by your custom implementation.

Since:

1.0

Version:

$Revision: 8102 $ $Date: 2006-04-25 16:09:10 -0600 (Tue, 25 Apr 2006) $

Author:

Gregory Block, Ralf Joachim

Nested Class Summary
- Nested classes/interfaces inherited from interface java.util.Map
  Map.Entry<K,V>

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_CAPACITY` Default capacity of cache.
`static Class<? extends Container>`	`DEFAULT_CONTAINER_CLASS` Default container class.
`static int`	`DEFAULT_CONTAINERS` Default number of containers for cache.
`static int`	`DEFAULT_MONITOR` Default monitor interval of cache in minutes.
`static Class<? extends AbstractReaper>`	`DEFAULT_REAPER_CLASS` Default reaper class.
`static int`	`DEFAULT_TTL` Default ttl of cache in seconds.
`static String`	`PARAM_CAPACITY` Mapped initialization parameter `capacity`.
`static String`	`PARAM_CONTAINER_CLASS` Mapped initialization parameter `container-class`.
`static String`	`PARAM_CONTAINERS` Mapped initialization parameter `containers`.
`static String`	`PARAM_MONITOR` Mapped initialization parameter `monitor`.
`static String`	`PARAM_REAPER_CLASS` Mapped initialization parameter `reaper-class`.
`static String`	`PARAM_TTL` Mapped initialization parameter `ttl`.

Fields inherited from interface org.castor.cache.Cache
DEFAULT_DEBUG, DEFAULT_NAME, DEFAULT_TYPE, PARAM_DEBUG, PARAM_NAME, PARAM_TYPE

Constructor Summary

Constructors
Constructor and Description

AbstractHashbelt()

Constructors
Constructor and Description
`AbstractHashbelt()`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`clear()`
`void`	`close()` Life-cycle method to allow custom resource cleanup for a cache implementation.
`boolean`	`containsKey(Object key)`
`boolean`	`containsValue(Object value)`
`Set<Map.Entry<Object,Object>>`	`entrySet()`
`int`	`getCapacity()` Get real capacity of this cache.
`protected Object`	`getObjectFromCache(Object key)` Get object currently associated with given key from cache.
`int`	`getTTL()` Get real ttl of this cache.
`void`	`initialize(Properties params)` Lyfe-cycle method to allow custom initialization of cache implementations.
`boolean`	`isEmpty()`
`Set<Object>`	`keySet()`
`protected ReadWriteLock`	`lock()` Get reference to the ReadWriteLock of this cache instance.
`protected Object`	`putObjectIntoCache(Object key, Object value)` Put given value with given key in cache.
`protected Object`	`removeObjectFromCache(Object key)` Remove any available association for given key.
`int`	`size()`
`Collection<Object>`	`values()`

Methods inherited from class org.castor.cache.AbstractBaseCache
expire, expireAll, getName, invokeMethod, invokeStaticMethod

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

Methods inherited from interface org.castor.cache.Cache
getType

Methods inherited from interface java.util.Map
equals, get, hashCode, put, putAll, remove

- Field Detail
  - PARAM_CONTAINERS
```
public static final String PARAM_CONTAINERS
```
    Mapped initialization parameter containers.
    
    See Also:
    Constant Field Values
  - PARAM_CONTAINER_CLASS
```
public static final String PARAM_CONTAINER_CLASS
```
    Mapped initialization parameter container-class.
    
    See Also:
    Constant Field Values
  - PARAM_REAPER_CLASS
```
public static final String PARAM_REAPER_CLASS
```
    Mapped initialization parameter reaper-class.
    
    See Also:
    Constant Field Values
  - PARAM_CAPACITY
```
public static final String PARAM_CAPACITY
```
    Mapped initialization parameter capacity.
    
    See Also:
    Constant Field Values
  - PARAM_TTL
```
public static final String PARAM_TTL
```
    Mapped initialization parameter ttl.
    
    See Also:
    Constant Field Values
  - PARAM_MONITOR
```
public static final String PARAM_MONITOR
```
    Mapped initialization parameter monitor.
    
    See Also:
    Constant Field Values
  - DEFAULT_CONTAINERS
```
public static final int DEFAULT_CONTAINERS
```
    Default number of containers for cache.
    
    See Also:
    Constant Field Values
  - DEFAULT_CONTAINER_CLASS
```
public static final Class<? extends Container> DEFAULT_CONTAINER_CLASS
```
    Default container class.
  - DEFAULT_REAPER_CLASS
```
public static final Class<? extends AbstractReaper> DEFAULT_REAPER_CLASS
```
    Default reaper class.
  - DEFAULT_CAPACITY
```
public static final int DEFAULT_CAPACITY
```
    Default capacity of cache.
    
    See Also:
    Constant Field Values
  - DEFAULT_TTL
```
public static final int DEFAULT_TTL
```
    Default ttl of cache in seconds.
    
    See Also:
    Constant Field Values
  - DEFAULT_MONITOR
```
public static final int DEFAULT_MONITOR
```
    Default monitor interval of cache in minutes.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - AbstractHashbelt
```
public AbstractHashbelt()
```
- Method Detail
  - initialize
```
public final void initialize(Properties params)
                      throws CacheAcquireException
```
    Lyfe-cycle method to allow custom initialization of cache implementations.
    
    Specified by:
    
    initialize in interface Cache
    
    Overrides:
    
    initialize in class AbstractBaseCache
    
    Parameters:
    params - Parameters to initialize the cache (e.g. name, capacity).
    
    Throws:
    
    CacheAcquireException - If cache can not be initialized.
  - close
```
public final void close()
```
    Life-cycle method to allow custom resource cleanup for a cache implementation.
    
    Specified by:
    
    close in interface Cache
    
    Overrides:
    
    close in class AbstractBaseCache
  - getCapacity
```
public final int getCapacity()
```
    Get real capacity of this cache.
    
    Returns:
    Real capacity of this cache.
  - getTTL
```
public final int getTTL()
```
    Get real ttl of this cache.
    
    Returns:
    Real ttl of this cache.
  - size
```
public final int size()
```
  - isEmpty
```
public final boolean isEmpty()
```
  - containsKey
```
public final boolean containsKey(Object key)
```
  - containsValue
```
public final boolean containsValue(Object value)
```
  - clear
```
public final void clear()
```
  - keySet
```
public final Set<Object> keySet()
```
  - values
```
public final Collection<Object> values()
```
  - entrySet
```
public final Set<Map.Entry<Object,Object>> entrySet()
```
  - lock
```
protected final ReadWriteLock lock()
```
    Get reference to the ReadWriteLock of this cache instance.
    
    Returns:
    ReadWriteLock to synchronize access to cache.
  - getObjectFromCache
```
protected final Object getObjectFromCache(Object key)
```
    Get object currently associated with given key from cache. Take care to acquire a read or write lock before calling this method and release the lock thereafter.
    
    Parameters:
    key - The key to return the associated object for.
    
    Returns:
    The object associated with given key.
  - putObjectIntoCache
```
protected final Object putObjectIntoCache(Object key,
                        Object value)
```
    Put given value with given key in cache. Return the object previously associated with key. Take care to acquire a write lock before calling this method and release the lock thereafter.
    
    Parameters:
    key - The key to associate the given value with.
    value - The value to associate with given key.
    
    Returns:
    The object previously associated with given key. null will be returned if no value has been associated with key.
  - removeObjectFromCache
```
protected final Object removeObjectFromCache(Object key)
```
    Remove any available association for given key. Take care to acquire a write lock before calling this method and release the lock thereafter.
    
    Parameters:
    key - The key to remove any previously associate value for.
    
    Returns:
    The object previously associated with given key. null will be returned if no value has been associated with key.

Class AbstractHashbelt

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Field Summary

Fields inherited from interface org.castor.cache.Cache

Constructor Summary

Method Summary

Methods inherited from class org.castor.cache.AbstractBaseCache

Methods inherited from class java.lang.Object

Methods inherited from interface org.castor.cache.Cache

Methods inherited from interface java.util.Map

Field Detail

PARAM_CONTAINERS

PARAM_CONTAINER_CLASS

PARAM_REAPER_CLASS

PARAM_CAPACITY

PARAM_TTL

PARAM_MONITOR

DEFAULT_CONTAINERS

DEFAULT_CONTAINER_CLASS

DEFAULT_REAPER_CLASS

DEFAULT_CAPACITY

DEFAULT_TTL

DEFAULT_MONITOR

Constructor Detail

AbstractHashbelt

Method Detail

initialize

close

getCapacity

getTTL

size

isEmpty

containsKey

containsValue

clear

keySet

values

entrySet

lock

getObjectFromCache

putObjectIntoCache

removeObjectFromCache