SK.gnome.dwarf.utils.cache
Class LRUCache

java.lang.Object
  SK.gnome.dwarf.GenericService
      SK.gnome.dwarf.thread.ThreadService
          SK.gnome.dwarf.utils.cache.LRUCache

All Implemented Interfaces:

Cache, Reportable, java.lang.Runnable, Service

Direct Known Subclasses:

LFUCache

public class LRUCache

extends ThreadService

implements Cache, Reportable

This class implements generic cache using the LRU algorithm.

This service implements the Cache interface using the Last-Recently-Used (LRU) alghorithm. The maximum cache size can be specified as well as the cache entry expiration timeout and the expiration checking interval. The cache does not allow null keys, but it allows null values.

The caching algorithm may be customized by overloading the three protected methods addEntry(LRUCache.CacheEntry), removeEntry() and updateEntries(LRUCache.CacheEntry). Thus the cache can be easily changed to use the Least-Frequently-Used (LFU) algorithm, or any other. All these methods operate on the entries list, which reflects the actual cache content.

This cache implementation is thread-safe.

Nested Class Summary

protected static class

LRUCache.CacheEntry This class represents the cached object.

Field Summary

protected java.util.LinkedList

entries Contains the CacheEntry instances representing the cached objects.

Fields inherited from class SK.gnome.dwarf.thread.ThreadService

daemon, thread

Fields inherited from class SK.gnome.dwarf.GenericService

initParameters, parent

Fields inherited from interface SK.gnome.dwarf.Service

INITIALIZED, LOG_DEBUG, LOG_ERROR, LOG_FATAL, LOG_INFO, LOG_TRACE, LOG_WARN, LOG_XFER, SHUTDOWN, STARTED, STOPPED

Constructor Summary

LRUCache(java.lang.String name)
Creates a new LRUCache with no size limit.

Method Summary

protected void	addEntry(LRUCache.CacheEntry entry) Adds a new entry to the list.
void	clear() Removes all objects from the cache.
protected boolean	enableThread() Enables the service thread.
java.lang.Object	get(java.lang.Object key) Returns an object from the cache.
protected void	loop() Performs the expiration checking.
void	put(java.lang.Object key, java.lang.Object obj) Puts the object to the cache.
java.lang.Object	remove(java.lang.Object key) Removes an object from the cache.
protected LRUCache.CacheEntry	removeEntry() Removes a cache entry from the list.
java.lang.String	report() Returns the service report.
void	setCheckingInterval(int interval) Sets the expiration checking interval.
void	setSize(int size) Sets the maximum cache size.
void	setTimeout(int timeout) Sets the cache entry expiration timeout.
void	shutdown() Shuts down the service; It clears the whole cache content as well by calling clear().
void	start() Starts the service.
protected void	updateEntries(LRUCache.CacheEntry entry) Updates the order of the cache entries in the list.

Methods inherited from class SK.gnome.dwarf.thread.ThreadService

finish, run, setDaemon, stop

Methods inherited from class SK.gnome.dwarf.GenericService

getAuthenticator, getAuthFacility, getFullName, getInitParameter, getInitParameterNames, getLogFacility, getLogger, getName, getParameters, getPrincipal, getShutdownTimeout, getState, init, log, log, login, logout, setAuthFacility, setInitParameters, setLogFacility, toString

Methods inherited from class java.lang.Object

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

Field Detail

entries

protected final java.util.LinkedList entries

Contains the CacheEntry instances representing the cached objects.

See Also:

addEntry(LRUCache.CacheEntry), removeEntry(), updateEntries(LRUCache.CacheEntry)

Constructor Detail

LRUCache

public LRUCache(java.lang.String name)

Creates a new LRUCache with no size limit.

Method Detail

setSize

public void setSize(int size)

Sets the maximum cache size.

Zero value means no limit, which is the default for newly created LRUCache objects.

Parameters:

size - the maximum size

See Also:

put(Object, Object)

setTimeout

public void setTimeout(int timeout)

Sets the cache entry expiration timeout.

Zero value means no expiration, i.e. the cache entry may be removed only when reaching the maximum cache size limit, which is the default.

Parameters:

timeout - the expiration time in seconds

See Also:

put(Object, Object)

setCheckingInterval

public void setCheckingInterval(int interval)

Sets the expiration checking interval.

Specifies the interval between two checks for expired cache entries. If the cache size limit is too high or the cache grows too quickly, you should consider to decrease this value - it would cause the cache to remove the expired entries more frequently.

The default value is given by the Constants.DEFAULT_CACHE_INTERVAL constant.

Parameters:

interval - the interval in seconds

shutdown

public void shutdown()

Shuts down the service;

It clears the whole cache content as well by calling clear().

Specified by:

shutdown in interface Service

Overrides:

shutdown in class ThreadService

start

public void start()
           throws ServiceException

Starts the service.

If the enableThread() method returns true, the service thread's priority is set to the minimum possible value.

Specified by:

start in interface Service

Overrides:

start in class ThreadService

Throws:

ServiceException

put

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

Puts the object to the cache.

If the maximum cache size limit has been set and the current cache size equals to this limit, a cache entry is removed and replaced by the new one.

Which cache entry will be removed is determined by the removeEntry() method. The entry is inserted to the entry list via the addEntry(LRUCache.CacheEntry) method. These two methods may be overriden to customize the caching algorithm.

Specified by:

put in interface Cache

Parameters:

key - the key

obj - the cached object

get

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

Returns an object from the cache.

The object (if exists) still remains in the cache for further use.

The updateEntries(LRUCache.CacheEntry) method is called with the argument representing the returned object. This method may be overriden to customize the caching algorithm.

Specified by:

get in interface Cache

Parameters:

key - the key

Returns:

the cached object or null if no object referenced by the given key was found

remove

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

Description copied from interface: Cache

Removes an object from the cache.

If an object implementing the Cacheable interface is being removed from the cache, the Cacheable.handleCacheEvent(Cacheable.CacheEvent) method must be invoked on it with the Cacheable.CacheEvent.REMOVED value.

Specified by:

remove in interface Cache

Parameters:

key - the key

Returns:

the cached object or null if no object referenced by the given key was found

clear

public void clear()

Description copied from interface: Cache

Removes all objects from the cache.

If an object implementing the Cacheable interface is being removed from the cache, the Cacheable.handleCacheEvent(Cacheable.CacheEvent) method must be invoked on it with the Cacheable.CacheEvent.INVALIDATED value.

Specified by:

clear in interface Cache

report

public java.lang.String report()

Returns the service report.

Returns the current/peak/total number of cached objects plus the number of cache hits and misses so far. You can use the statistics to tune up the cache using the maximum cache size limit, the cache entry expiration timeout and the expiration checking interval.

Note: When clearing the cache via the clear() method, only the current number of the cached entries is reset to zero.

Specified by:

report in interface Reportable

Returns:

current service state in a human-readable format

enableThread

protected boolean enableThread()

Enables the service thread.

Returns true if the cache entry expiration timeout has been set to a value greater than zero.

Overrides:

enableThread in class ThreadService

Returns:

true if the thread is enabled

loop

protected void loop()

Performs the expiration checking.

If the cache entry expiration timeout is set to a value greater than zero, this method removes all expired cache entries from the cache.

Overrides:

loop in class ThreadService

See Also:

setTimeout(int), setCheckingInterval(int)

addEntry

protected void addEntry(LRUCache.CacheEntry entry)

Adds a new entry to the list.

This method is called if a new object is being added to the cache. It must add the corresponding entry to the entries list at a desired position.

The default implementation adds the given entry to the end of the list.

Parameters:

entry - the cache entry representing the object to be added to the cache

removeEntry

protected LRUCache.CacheEntry removeEntry()

Removes a cache entry from the list.

This method is called if the maximum cache size is reached and an object must be removed from the cache prior to inserting a new one. It has to look at the entries list and remove just one element from the list.

The default implementation removes the last element of the list.

Returns:

CacheEntry the cache entry representing the object to be removed

updateEntries

protected void updateEntries(LRUCache.CacheEntry entry)

Updates the order of the cache entries in the list.

This method is called if an object is returned from the cache. It should keep the list entries in a desired order.

The default implementation removes the given element from the list and re-inserts it at the start of the list.

Parameters:

entry - the cache entry representing the cached object