jdbm.helper

## Interface CachePolicy<K,V>

All Known Implementing Classes:
  MRU, SoftCache

    public interface CachePolicy<K,V>

CachePolicity is an abstraction for different cache policies. (ie. MRU, time-based, soft-refs, ...)

Author:
  Alex Boisvert, Dilum Ranatunga

### Method Summary

Methods
`void` `addListener(CachePolicyListener<V> listener)` Add a listener to this cache policy.
`Enumeration<V>` `elements()` Enumerate through the objects currently in the cache.
`V` `get(K key)` Obtain the object stored under the key specified.
`void` `put(K key, V value)` Place an object in the cache.
`void` `remove(K key)` Remove the object stored under the key specified.
`void` `removeAll()` Remove all objects from the cache.
`void` `removeListener(CachePolicyListener<V> listener)` Remove a listener from this cache policy.

### Method Detail

#### put

    void put(K key,
           V value)
             throws CacheEvictionException

Place an object in the cache. If the cache does not currently contain an object for the key specified, this mapping is added. If an object currently exists under the specified key, the current object is replaced with the new object.

If the changes to the cache cause the eviction of any objects stored under other key(s), events corresponding to the evictions are fired for each object. If an event listener is unable to handle the eviction, and throws a cache eviction exception, that exception is propagated to the caller. If such an exception is thrown, the cache itself should be left as it was before the `put()` operation was invoked: the the object whose eviction failed is still in the cache, and the new insertion or modification is reverted.

Parameters:
  `key` - key for the cached object
  `value` - the cached object
Throws:
  `CacheEvictionException` - propagated if, while evicting objects to make room for new object, an eviction listener encountered this problem.

#### get

    V get(K key)

Obtain the object stored under the key specified.

Parameters:
  `key` - key the object was cached under
Returns:
  the object if it is still in the cache, null otherwise.

#### remove

    void remove(K key)

Remove the object stored under the key specified. Note that since eviction notices are only fired when objects under different keys are evicted, no event is fired for any object stored under this key (see `put( )`).

Parameters:
  `key` - key the object was stored in the cache under.

#### removeAll

    void removeAll()

Remove all objects from the cache. Consistent with `remove( )`, no eviction notices are fired.

#### elements

    Enumeration<V> elements()

Enumerate through the objects currently in the cache.

#### addListener

    void addListener(CachePolicyListener<V> listener)
                     throws IllegalArgumentException

Add a listener to this cache policy.

If this cache policy already contains a listener that is equal to the one being added, this call has no effect.

Parameters:
  `listener` - the (non-null) listener to add to this policy
Throws:
  `IllegalArgumentException` - if listener is null.

#### removeListener

    void removeListener(CachePolicyListener<V> listener)

Remove a listener from this cache policy. The listener is found using object equality, not identity.

Parameters:
  `listener` - the listener to remove from this policy