org.sandev.basics.util
Class IDCacheBase

java.lang.Object
  org.sandev.basics.util.IDCacheBase

All Implemented Interfaces:

IDCache

Direct Known Subclasses:

NamedSingletonIDCache, NodeLocalIDCache, SingletonIDCache

public class IDCacheBase
extends java.lang.Object
implements IDCache

Provides common methods for all IDCache implementations. This class provides utilities and a framework for cache implementation using a Map, override the init method to change what kind of map is used.

The design goal of this cache is to provide something reliable that doesn't suck up a huge amount of memory. It has to be fast enough to provide a significant performance improvement over a database query, but that's not hard given that a getting anything out of the db is going to be around 5 million times slower.

Java 6 provides a ConcurrentSkipListMap which would be a pretty cool basis, but we are still running on Java 4 in spots (at the time of this writing) so that's a ways off still. For now all access just queues up from everything being synchronized.

Field Summary

protected IDCacheCallback	callback The callback for this cache.
protected java.util.Map	map The caching data structure.
protected boolean	revisionCheck If true, then only newer revisions of a message will be accepted by put.
protected long	timeToLiveMillis The time in milliseconds that an item may exist in the cache before it is subject to cleanup.

Constructor Summary

IDCacheBase()
Default ctor calls init

Method Summary

boolean	checkRevisionNumber() accessor for revisionCheck
void	cleanup() Clean out any entries older than the time to live value.
void	clear() Clear all entries from the cache.
SandCollectionMessage	find(SandQueryMessage sqm) Return a collection of the messages in the cache matching the specified query.
IDCacheCallback	getCallback() accessor for callback
SandPersistMessage	getInstance(long id) Return the instance corresponding to the given id, or null if not found.
java.util.Map	getMap() Return the underlying Map for this cache if available.
SandPersistMessage[]	getSortedItems() Returns an array of all the items in the cache, sorted by lastAccessedTime with the oldest items first.
CacheStats	getStats(int nold) Return the current use statistics for this cache
long	getTimeToLiveMillis() accessor for timeToLiveMillis
static java.lang.Object	idToKey(long id) We need an object to use as a key.
void	init() Initialize the Map to a synchronized TreeMap.
boolean	putInstance(SandPersistMessage msg) Write the given instance into the cache provided it is not null.
SandPersistMessage	removeInstance(long id) Remove the given instance from the cache if it exists.
void	setCallback(IDCacheCallback idcc) mutator for callback
void	setRevisionCheck(boolean val) mutator for revisionCheck
void	setTimeToLiveMillis(long val) mutator for timeToLiveMillis

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

map

protected java.util.Map map

The caching data structure. See the init method.

revisionCheck

protected boolean revisionCheck

If true, then only newer revisions of a message will be accepted by put. Older or equivalent revisions will be ignored and put will return false. By default revisionCheck is true.

callback

protected IDCacheCallback callback

The callback for this cache. May be set or not.

timeToLiveMillis

protected long timeToLiveMillis

The time in milliseconds that an item may exist in the cache before it is subject to cleanup.

Constructor Detail

IDCacheBase

public IDCacheBase()

Default ctor calls init

Method Detail

checkRevisionNumber

public boolean checkRevisionNumber()

accessor for revisionCheck

setRevisionCheck

public void setRevisionCheck(boolean val)

mutator for revisionCheck

getCallback

public IDCacheCallback getCallback()

accessor for callback

Specified by:

getCallback in interface IDCache

setCallback

public void setCallback(IDCacheCallback idcc)

mutator for callback

Specified by:

setCallback in interface IDCache

getTimeToLiveMillis

public long getTimeToLiveMillis()

accessor for timeToLiveMillis

Specified by:

getTimeToLiveMillis in interface IDCache

setTimeToLiveMillis

public void setTimeToLiveMillis(long val)

mutator for timeToLiveMillis

Specified by:

setTimeToLiveMillis in interface IDCache

putInstance

public boolean putInstance(SandPersistMessage msg)

Write the given instance into the cache provided it is not null. If revision number checking is enabled for this cache (enabled by default in the init method), and the instance was already cached, then the existing instance is only replaced if the revision number is greater than the instance that is already there. This avoids unnecessary writes.

Specified by:

putInstance in interface IDCache

getInstance

public SandPersistMessage getInstance(long id)

Return the instance corresponding to the given id, or null if not found. This updates the lastAccessedTime in the given instance to allow for age tracking.

Specified by:

getInstance in interface IDCache

removeInstance

public SandPersistMessage removeInstance(long id)

Remove the given instance from the cache if it exists.

Specified by:

removeInstance in interface IDCache

clear

public void clear()

Clear all entries from the cache.

Specified by:

clear in interface IDCache

getMap

public java.util.Map getMap()

Return the underlying Map for this cache if available. This method is not thread safe and should not be used for normal application development. Use the find method instead.

Specified by:

getMap in interface IDCache

find

public SandCollectionMessage find(SandQueryMessage sqm)

Return a collection of the messages in the cache matching the specified query. This iterates through the underlying map returning everything matching the specification.

It is the callers responsibility to

1. Ensure the given query is appropriately restricted
2. Ensure the resulting elements are appropriately restricted

In short, the caller needs to ensure their AuthFilter.matchRestrictions are already incorporated into the query, and filter what is returned based on the access allowed.

Specified by:

find in interface IDCache

idToKey

public static java.lang.Object idToKey(long id)

We need an object to use as a key. From what I can tell, two separate Long objects with the same value aren't necessarily the same hash, so they don't refer to the same key. I know this works if you intern the String value, so that's what we do.

getSortedItems

public SandPersistMessage[] getSortedItems()

Returns an array of all the items in the cache, sorted by lastAccessedTime with the oldest items first. Anything that can't be removed will have its lastAccessedTime set to the current time plus 24 hours to guarantee it won't be pulled as the oldest.

getStats

public CacheStats getStats(int nold)

Return the current use statistics for this cache

Specified by:

getStats in interface IDCache

cleanup

public void cleanup()

Clean out any entries older than the time to live value.

Specified by:

cleanup in interface IDCache

init

public void init()

Initialize the Map to a synchronized TreeMap. While the access time for a tree is slightly higher than a HashMap, it is still orders of magnitude faster than a database lookup, and it is far more memory efficient. A default HashMap is rehashed (doubled in size) when the load factor hits 3/4 full. That makes it pretty innefficient for storing large amounts of data.