org.sandev.basics.util
Interface IDCache

All Known Implementing Classes:

IDCacheBase, NamedSingletonIDCache, NodeLocalIDCache, SingletonIDCache

public interface IDCache

Defines a reliable and efficient lookup of a persistent object instance via its unique identifier. An IDCache works like a local hashtable of global instance data.

It is recommended, but not required, that an IDCache implementation provide a default no-args constructor. Other ctors may take additional parameters to provide for size limits to be enforced during calls to the putInstance method, or to automatically handle proactive updates.

See Persist.html in the top level docs for overview information on caching.

Method Summary

void	cleanup() Clean up any older items that have exceeded their time to live.
void	clear() Remove all entries from this cache.
SandCollectionMessage	find(SandQueryMessage query) Iterate through the cache finding all instances that match the given query and return the corresponding collection of all instances found.
IDCacheCallback	getCallback() Returns the callback if one has been set.
SandPersistMessage	getInstance(long id) Given a persistent ID, return the associated message instance.
java.util.Map	getMap() Return the underlying map used by the cache.
CacheStats	getStats(int nold) Return a CacheStats message showing the specified number of older items that will be replaced to free space.
long	getTimeToLiveMillis() Return the millisecond time to live for this heap.
boolean	putInstance(SandPersistMessage msg) Given a persistent messsage, store it in the cache.
SandPersistMessage	removeInstance(long id) Given a persistent ID, remove it from the cache.
void	setCallback(IDCacheCallback callback) Sets the callback for this cache.
void	setTimeToLiveMillis(long millis) Set the millisecond time to live in the cache.

Method Detail

putInstance

boolean putInstance(SandPersistMessage msg)

Given a persistent messsage, store it in the cache. Returns true if the cached instance was replaced or added. Returns false if the instance already exists but was not replaced.

An instance will always be replaced if its revision number is greater than that of the cached instance. If the revision number is the same, and the cache already contains an instance then the cache may choose to keep the instance it already has. This allows cache implementations to maintain their internal state without unnecessary updates.

getInstance

SandPersistMessage getInstance(long id)

Given a persistent ID, return the associated message instance. Return null if the instance cannot be retrieved.

removeInstance

SandPersistMessage removeInstance(long id)

Given a persistent ID, remove it from the cache. Return null if the instance cannot be retrieved.

clear

void clear()

Remove all entries from this cache.

getMap

java.util.Map getMap()

Return the underlying map used by the cache. Since this returns a live reference to the map, manipulating the map directly can invalidate or corrupt the contents of the cache. Generally the putInstance(org.sandev.basics.structs.SandPersistMessage) and removeInstance(long) methods should be used for cache manipulation, and this method should only be used for read-only access like iteration over the map's contents. This method may throw a ConcurrentModificationException and is not recommended for general use.

Returns null if the IDCache is not backed by a map.

find

SandCollectionMessage find(SandQueryMessage query)

Iterate through the cache finding all instances that match the given query and return the corresponding collection of all instances found.

getStats

CacheStats getStats(int nold)

Return a CacheStats message showing the specified number of older items that will be replaced to free space.

getCallback

IDCacheCallback getCallback()

Returns the callback if one has been set.

setCallback

void setCallback(IDCacheCallback callback)

Sets the callback for this cache.

getTimeToLiveMillis

long getTimeToLiveMillis()

Return the millisecond time to live for this heap.

setTimeToLiveMillis

void setTimeToLiveMillis(long millis)

Set the millisecond time to live in the cache. Any item that hasn't been accessed in this amount of time will be removed on next cleanup. A zero value means the time to live is infinite.

cleanup

void cleanup()

Clean up any older items that have exceeded their time to live.