org.jwarp.service.cache
Class Cache

java.lang.Object
  |
  +--org.jwarp.service.cache.Cache

All Implemented Interfaces:

ICache

public class Cache

extends java.lang.Object

implements ICache

This class implments the ICache interface. It implements all the basic stuff, such us controlling access of the items, updating the cached data, e.g. removing unused data. For each cache instance a CacheUpdateThread is started which is responsible for regularely calling the cache's update method. The exact behaviour of the cache can be controlled by several settings:

maxComponents:	This setting is a boundery for the objects maximally hold within the cache. If set to -1 this setting is switched off.
maxTime:	Determines the maximal time an item is hold in the cache. When this time is over the object will be removed from the cache. This setting garantees a minimal actuality state of each object within the cache. If this is set to -1 then this setting is ignored.
minAccess:	This setting determines the minimum access count an object must reach to be kept within the cache. The period checked is identical to the update period of the update thread. The value provided is a start value. If this is the only setting actually set the minAccess value is used as provided. Other settings such as the maxComponents setting lead also in a internal dynamic adaptation of the minAccess value to get the cache size as defined in the maxComponents setting.
updateInterval:	This is the period when the update thread is started. The update thread is responsible for throwing objects out the cache depending on the cache settings explained above.
sensibility:	The sensibility is the minimum difference of accesses made in maximum to a cache entry so the internal LRU table is made bigger/smaller.	tolerance:	The tolerance is the amount which the total cache size may grow bigger than the maximum objects count. Shortly everytime the total objects count in the cache supercedes the number of maximum objects allowed plus the tolerance setting an extraordinary update thread is started.	granularity:	The amount of access classes that are used for classifying the number of accesses made to objects. If you have a very big cache with lots of objects and different accesses then you may set a bigger value here. Default is 30.	tracing:	If you enable tracing all the caches activities are stored in a internal structure. You can the tell the cache to print out its activities to a print writer. The maximum number of traced items can be limited with the setMaxTraceItems method.

Field Summary

protected long	currentMinAccess Determines how many accesses should be made so an object can stay in the cache.
protected boolean	debugging Turns on or off debugging message.
protected java.util.Hashtable	objects The actually cashed objects.
protected int	reactionSensiblity The sensibility is the minimum difference of accesses made in maximum to a cache entry so the internal LRU table is made bigger/smaller

Constructor Summary

Cache()
Creates a default cache.

Cache(long updateInterval)
Creates a default cache setting the caches update interval.

Cache(java.util.Properties properties)
Creates a default cache setting the caches value with the properties passed..

Method Summary

void	flush() Flush the cache.
java.lang.Object	get(java.lang.Object key) Returns the cached object reference or null if no object matched.
boolean	getDebugging() Returns if debugging is enabled.
java.util.Enumeration	getKeys() Return the currently stored keys.
int	getObjectCount() Returns the currently stored objects number.
java.util.Enumeration	getObjects() Returns an enumeration of the currently object in the cache.
int	getTolerance() Returns the current tolerance
long	getUpdateIntervall() Returns the caches update interval.
boolean	isTracing() Returns if the cache is currently tracing its activities.
void	printCacheState(java.io.PrintWriter pw) Prints out the caches current status to the print writer provided.
void	printTrace(java.io.PrintWriter pw, boolean printDetails) This prints out the trace information on the writer passed.
void	put(java.lang.Object key, java.lang.Object object) Puts a new object in the cache.
java.lang.Object	remove(java.lang.Object key) Remove explicitely an object from the cache.
void	resetTracing() Resets tracing.
void	setDebugging(boolean val) Switches debugging on or off.
protected void	setGranularity(int accessClassCount) Set the granularity of the access statistics.
void	setMaxComponents(int number) Set the maximum numbers of objects of the cache.
void	setMaxComponents(int number, int tolerance) Sets the maximum number of objects to be hold in the cache.
void	setMaxTime(long maxTime) Set the maximal time an object is hold in the cache.
void	setMaxTracingItems(int max) Sets the maximum tracing barrier.
void	setMinAccess(int minAccess) Set the minimalAccess default setting.
void	setReactionSensibility(int sens) This changes the sensibility which is used for adapting the currentMinAccess setting when the cache is updated.
void	setTolerance(int tolerance) Sets the tolerance of the cache for calling the update thread when too many objects are inserted into the cache and the update thread could not remove the superfluous ones.
void	setTracing(boolean tracing) Enable or disable tracing of the caches activity.
void	setTracing(boolean tracing, int maxItems) Enable or disable tracing of the caches activity.
void	setUpdateIntervall(long millis) Sets the update interval.
void	updateCache() This method will be called by the update thread.

Methods inherited from class java.lang.Object

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

Field Detail

objects

protected java.util.Hashtable objects

The actually cashed objects.

currentMinAccess

protected long currentMinAccess

Determines how many accesses should be made so an object can stay in the cache. Its value is recalcultating during each update of the cache depending on the accesses made past the last period. So a simple LRU algorithm is implemented.

debugging

protected boolean debugging

Turns on or off debugging message.

reactionSensiblity

protected int reactionSensiblity

The sensibility is the minimum difference of accesses made in maximum to a cache entry so the internal LRU table is made bigger/smaller

Constructor Detail

Cache

public Cache()

Creates a default cache. The default settings are:
Update period in ms: 30000
Min Access: 3
Current min Access: 3
Reaction sensiblity: 10
Max components: 200
Max time:10000

Cache

public Cache(long updateInterval)

Creates a default cache setting the caches update interval. Further default settings are:
Min Access: 3
Current min Access: 3
Reaction sensiblity: 10
Max components: 200
Max time:10000

Parameters:

The - update interval in millis

Cache

public Cache(java.util.Properties properties)

Creates a default cache setting the caches value with the properties passed.. The properties are
CACHE_UPDATE_MS The update time in ms
CACHE_DEBUGGING Debugging (true/false)
CACHE_MIN_ACCESS min access, -1 off
CACHE_MAX_COMPONENTS max components, -1 off
CACHE_MAX_TIME max cached time, -1 off
CACHE_ACCESS_SENSIBILITY reaction sensibility
CACHE_TOLERANCE: tolerance, default is maxComponents/2 CACHE_GRANULARITY: granularity, default is 30 CACHE_TRACING: tracing switch (true/false) CACHE_TRACE_MAX_OBJECTS: max tracing items (kind of memory limit), default 100000

Method Detail

get

public java.lang.Object get(java.lang.Object key)

Returns the cached object reference or null if no object matched. Before returning the objecst the access statistics are updated.

Specified by:

get in interface ICache

Parameters:

The - object key

Returns:

The object from the cache or null (cache miss)

put

public void put(java.lang.Object key,
                java.lang.Object object)

Puts a new object in the cache. The object is wrapped in an internal structure storing the access data. After the object is added to the cache it is tested if the maximal objects size is exceeded. If so the update thread is waken up.

Specified by:

put in interface ICache

Parameters:

key - The objects key

object - The object to be stored

setTolerance

public void setTolerance(int tolerance)

Sets the tolerance of the cache for calling the update thread when too many objects are inserted into the cache and the update thread could not remove the superfluous ones. As a start you can set 50 % of the total maximal object count. If no maximal object count is set then this setting is ignored. Values less/equals to zero will be ignored.

Parameters:

tolerance - the tolerance value

getTolerance

public int getTolerance()

Returns the current tolerance

Returns:

The current tolerance

setDebugging

public void setDebugging(boolean val)

Switches debugging on or off. If debugging is switched on the cache writes out all his work to com.cspb.fis.util.DebugLog.getInstance.Set this setting only to true if need it for bug tracking since it slows down the cache.

Specified by:

setDebugging in interface ICache

Parameters:

val - true if you want to enable debugging

getDebugging

public boolean getDebugging()

Returns if debugging is enabled.

Specified by:

getDebugging in interface ICache

Returns:

true if debugging is enabled.

setTracing

public void setTracing(boolean tracing,
                       int maxItems)

Enable or disable tracing of the caches activity. When tracing is enabled you can printout the caches activity to a printstream. Note that tracing is expensive and slows down quite a lot the cache. Additionally memory is filled with tracing items until the maximal tracing item count is reached. After reaching this barrier tracing is stopped until you reset tracing with the resetTracing method.

Parameters:

tracing - Enable/Disable tracing

maxItems - The maximal items to be traced

setTracing

public void setTracing(boolean tracing)

Enable or disable tracing of the caches activity. When tracing is enabled you can printout the caches activity to a printstream. Note that tracing is expensive and slows down quite a lot the cache. Additionally memory is filled with tracing items until the maximal tracing item count is reached. After reaching this barrier tracing is stopped until you reset tracing with the resetTracing method.

isTracing

public boolean isTracing()

Returns if the cache is currently tracing its activities.

Returns:

true if tracing is enabled

resetTracing

public void resetTracing()

Resets tracing. All tracing information is removed.

setMaxTracingItems

public void setMaxTracingItems(int max)

Sets the maximum tracing barrier.

Parameters:

The - maximal tracing items stored.

printTrace

public void printTrace(java.io.PrintWriter pw,
                       boolean printDetails)

This prints out the trace information on the writer passed.

Parameters:

pw - The target printwriter.

remove

public java.lang.Object remove(java.lang.Object key)

Remove explicitely an object from the cache. Use this method if an object was deleted or removed otherwise from the object universe.

Specified by:

remove in interface ICache

Parameters:

key - The objects key

setUpdateIntervall

public void setUpdateIntervall(long millis)

Sets the update interval. The update interval determines the period length when the update thread is calling the cache's update method for updating the caches data and status.

Specified by:

setUpdateIntervall in interface ICache

Parameters:

millis - The updateInterval in ms

getUpdateIntervall

public long getUpdateIntervall()

Returns the caches update interval.

Returns:

The update interval

setMaxComponents

public void setMaxComponents(int number,
                             int tolerance)

Sets the maximum number of objects to be hold in the cache. Actually not always there are exactly that number of objects in the cache. This settings is primarely used for determining if the currentMinAccess setting should be cahged to dynamically adapt the caches sensibility.

setMaxComponents

public void setMaxComponents(int number)

Description copied from interface: ICache

Set the maximum numbers of objects of the cache.

Specified by:

setMaxComponents in interface ICache

getObjectCount

public int getObjectCount()

Returns the currently stored objects number.

Specified by:

getObjectCount in interface ICache

Returns:

The number of objects in the cache.

getObjects

public java.util.Enumeration getObjects()

Returns an enumeration of the currently object in the cache.

Specified by:

getObjects in interface ICache

Returns:

The current objects

getKeys

public java.util.Enumeration getKeys()

Return the currently stored keys.

Specified by:

getKeys in interface ICache

Returns:

The keys

flush

public void flush()

Flush the cache. This removes all objects and references.

Specified by:

flush in interface ICache

setReactionSensibility

public void setReactionSensibility(int sens)

This changes the sensibility which is used for adapting the currentMinAccess setting when the cache is updated. The currentMinAcces is used to determine which objects should be deleted out of the cache or kept. The sensibility determines how much additional/fewer accesses an object must have on the next update.

Specified by:

setReactionSensibility in interface ICache

Parameters:

The - sensibility

setMinAccess

public void setMinAccess(int minAccess)

Set the minimalAccess default setting. Also the current access setting is adapted to the new value.

Specified by:

setMinAccess in interface ICache

Parameters:

The - minimal acces number.

setMaxTime

public void setMaxTime(long maxTime)

Set the maximal time an object is hold in the cache. If you want objects probebly to be unlimeted stored in the cache, set this to -1;

Specified by:

setMaxTime in interface ICache

Parameters:

The - maximal hosting time.

updateCache

public void updateCache()

This method will be called by the update thread. It determines if there are objects to be removed from the cache. The order is:
(1): Elements exceeding the maximum time to be cached (if defined)
(2): Elements not enough access the last period. The minAccess count is adapted to the effective period when this method is called.
(3): If there are still too much elements then all elements that exceed the maximum element count will be removed. The order of removal is based a LRU algorithm approximation.

Specified by:

updateCache in interface ICache

setGranularity

protected void setGranularity(int accessClassCount)

Set the granularity of the access statistics. The distribution of accesses of the cache objects is classified in this number of access classes. The more objects you cache and the more acceses you have, you must raise this number. Be also aware that the higher this value is the more adminisrtation overhead will be generated. Note that a minimum value of 5 slots must be provided. All values less than 5 will be ignored.

Parameters:

accessClassCount - The number of classification slots

printCacheState

public void printCacheState(java.io.PrintWriter pw)

Prints out the caches current status to the print writer provided.

Parameters:

The - printwriter to printout the caches contents.