com.bigdata.cache
Interface ICachePolicy<K,T>

All Known Implementing Classes:

LRUCache, WeakValueCache

public interface ICachePolicy<K,T>

Interface for cache policy.

The semantics of this interface are generally specified in terms of a hard reference cache backing a weak (or soft) reference cache. Examples of methods on the interface whose semantics are determined by the hard reference cache include:

• iterator() - visitation order and membership is determined by the backing hard reference cache.
• entryIterator() - visitation order and membership is determined by the backing hard reference cache.
• size() - membership is determined by the backing hard reference cache.
• capacity() - the capacity of the backing hard reference cache.
• #setListener() - eviction notices are fired when entries are evicted from the hard reference cache.

The rationale for this is that the cache iterator methods are used to perform installs of dirty objects from the cache onto the persistence layer during a commit. Since clear references are not reachable, eviction notices are fired when entries are evicted from the hard reference cache. Those notices must be used to install dirty objects onto the persistence layer, in which case the entry for that object in the weak reference cache is marked as clean. When properly integrated with the persistence layer, this provides a guarantee that the iterators will never fail to visit a dirty entry in the cache. For consistency with the iterator methods, size() returns the number of entries in the hard reference cache. Neither visitation of nor counting of all weak cache entries in and of itself is not a foreseen use case and those semantics not supported by this interface.

Version:

$Id: ICachePolicy.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

thompsonbry

TODO:

long oid to Object oid? The advantages of this are: (1) it allows us to create a flyweight object a long integer and pass it around, thereby avoiding many conditions under which we mint new Longs; (2) the OID math may be encapsulated on that flyweight object; (3) we can use a different OID object for each backend if necessary; (4) we can change the size of the OID more transparently since more code will not depend on it being a [long] data type. (The IGenericData would still use long internally.) (extSer might accept an Object for its writePackedOID() method)., expose a means to test whether a cache entry is dirty, but consider the interactions implied for the weak value cache. one way to approach this is to expose getEntry( long key ). The problem with this is that it does not encapsulate the odder semantics of the weak value cache.

Method Summary

int	capacity() Return the capacity of the hard reference cache.
void	clear() Clear all objects from the cache.
Iterator<ICacheEntry<K,T>>	entryIterator() Return an iterator that will visit the ICacheEntry objects in the cache.
T	get(K oid) Return the indicated object from the cache or null if the object is not in cache.
ICacheListener<K,T>	getCacheListener() Return the cache eviction listener.
Iterator<T>	iterator() Return an iterator that will visit the application objects in the cache.
void	put(K oid, T obj, boolean dirty) Insert or "touch" this object in the cache.
T	remove(K oid) Remove the indicated object from the cache.
void	setListener(ICacheListener<K,T> listener) Sets the cache eviction listener on the hard reference cache.
int	size() Return the #of entries in the hard reference cache.

Method Detail

setListener

void setListener(ICacheListener<K,T> listener)

Sets the cache eviction listener on the hard reference cache. Eviction notices are fired when objects are evicted from the hard reference cache.

Parameters:

listener - The listener or null to remove any listener.

getCacheListener

ICacheListener<K,T> getCacheListener()

Return the cache eviction listener.

put

void put(K oid,
         T obj,
         boolean dirty)

Insert or "touch" this object in the cache.

Parameters:

oid - The object identifier.

obj - The object.

dirty - True iff the object is dirty.

Throws:

IllegalStateException - If a different object is in the cache under the specified object identifier.

get

T get(K oid)

Return the indicated object from the cache or null if the object is not in cache.

Parameters:

oid - The object identifier.

Returns:

The object or null iff it is not in cache.

remove

T remove(K oid)

Remove the indicated object from the cache.

Parameters:

oid - The object identifier.

Returns:

The object in the cache for that object identifier or null if there was no object under that identifier.

clear

void clear()

Clear all objects from the cache. This method may be used to reset the cache when a transaction is being rolled back. Cache eviction notices are NOT fired when this method is called.

iterator

Iterator<T> iterator()

Return an iterator that will visit the application objects in the cache. The visitation order is determined by the hard reference cache policy. If the cache policy is ordered, then the visitation order reflects that order.

See Also:

entryIterator()

entryIterator

Iterator<ICacheEntry<K,T>> entryIterator()

Return an iterator that will visit the ICacheEntry objects in the cache. The visitation order is determined by the hard reference cache policy. If the cache policy is ordered, then the visitation order reflects that order.

Note: This method is used to force dirty objects in the cache to the persistence layer during a transaction commit since it visits entries and not referents, thereby providing access to the cache entry metadata.

Returns:

Iterator visiting ICacheEntry objects. If this is a weak reference cache, then the iterator visits the entries in the delegate hard reference cache.

See Also:

ICacheEntry, iterator()

size

int size()

Return the #of entries in the hard reference cache.

Returns:

The #of entries in the hard reference cache.

capacity

int capacity()

Return the capacity of the hard reference cache.

Returns:

The capacity of the hard reference cache.