org.jboss.shotoku.cache
Class CacheItem<K,T>

java.lang.Object
  org.jboss.shotoku.cache.CacheItem<K,T>

Type Parameters:

K - Type of the key of the objects held in cache. The keys should bahave well as map keys (most probably, the hashCode() and equals() methods should be overriden).

T - Type of the objects that will be stored in the cache.

All Implemented Interfaces:

CacheItemOperations<K,T>, CacheItemUser<K,T>

public class CacheItem<K,T>
extends java.lang.Object
implements CacheItemOperations<K,T>

Use this class if you want to store objects in a cache that will be updated on a regular intervals of time, by a service daemon thread. All data is held in one node of a org.jboss.cache.TreeCache. Instances of this class can be obtained using the create(CacheItemDataSource) and create(CacheItemDataSource, Fqn, String, long) methods, provided a CacheItemDataSource. If a key is requested for the first time, it is initialized with the CacheItemDataSource.init(Object) method. Later, the CacheItemDataSource.update(Object, Object) method is called to (possibly) update the currently held value. The cache item will be auto-registered in the service upon construction --- so take care when constructing objects of this class. When you want to remove all keys, from the TreeCache node, that are handled by this cache item, simply call the unregister() method.

Author:

Adam Warski

Method Summary

static <K,T> CacheItemUser<K,T>	create(CacheItemDataSource<K,T> dataSource) Creates and registeres a new cache item, with default parameter values (see create(CacheItemDataSource, Fqn, String, long)): the fqn will be auto-generated, a default cache mbean name will be used, update will happen on each service thread update and there will be no limit on the length of a key update.
static <K,T> CacheItemUser<K,T>	create(CacheItemDataSource<K,T> dataSource, Fqn fqn, java.lang.String mbeanName, long interval) Creates and registeres a new cache item.
T	get(K key) Gets an object that is bound to the given key in the associated TreeCache node.
Fqn	getFqn()
int	getId()
java.lang.String	getInfo()
long	getInterval()
ConcurrentSet<K>	getKeysDuringUpdate()
java.util.concurrent.ConcurrentMap<K,java.lang.Throwable>	getKeysExceptions()
java.util.concurrent.ConcurrentMap<K,java.lang.Long>	getKeysUpdates()
java.lang.String	getMbeanName()
java.lang.String	getName()
void	register() Registers this cache item in the service.
void	reportUpdateOk(K key) Reports that an update of a key ended wihtout any exceptions.
void	reportUpdateWithException(K key, java.lang.Throwable t) Reports that an update of a key ended with an exception.
void	resetKey(java.lang.Object key) Resets the given key, that is, it's update status.
void	setInterval(long interval)
void	unregister() Removes all keys handled by this cache item from the associated TreeCache node and stops updates on this cache item.
void	update() Called by the service update thread to update all keys and associated values.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static <K,T> CacheItemUser<K,T> create(CacheItemDataSource<K,T> dataSource)

Creates and registeres a new cache item, with default parameter values (see create(CacheItemDataSource, Fqn, String, long)): the fqn will be auto-generated, a default cache mbean name will be used, update will happen on each service thread update and there will be no limit on the length of a key update.

Parameters:

dataSource - Data source from which the resulting cache item will read.

create

public static <K,T> CacheItemUser<K,T> create(CacheItemDataSource<K,T> dataSource,
                                              Fqn fqn,
                                              java.lang.String mbeanName,
                                              long interval)

Creates and registeres a new cache item.

Parameters:

dataSource - Data source from which the resulting cache item will read.

fqn - An fqn of the node in TreeCache, where data should be held. If it is null, a unique fqn will be auto-generated for this cache item.

mbeanName - A name of an RenewableCacheServiceMBean mbean, which should be used to perform cache operations. This mbeans holds a reference to a org.jboss.cache.TreeCache. If it is null, a default mbean name will be used.

interval - Interval at which the update operation will be executed. Effectively, the interval will be rounded to the nearest multiplicity of the service update thread interval. The interval should be given in milliseconds. If it is 0, the update() method will be executed on every service thread update.

register

public void register()

Description copied from interface: CacheItemUser

Registers this cache item in the service. This method is automatically called when creating the cache item (using create(CacheItemDataSource)), so you will only need to use it if you previously manually unregistered the cache item using CacheItemUser.unregister().

Specified by:

register in interface CacheItemUser<K,T>

unregister

public void unregister()

Description copied from interface: CacheItemUser

Removes all keys handled by this cache item from the associated TreeCache node and stops updates on this cache item.

Specified by:

unregister in interface CacheItemUser<K,T>

getFqn

public Fqn getFqn()

Specified by:

getFqn in interface CacheItemUser<K,T>

Returns:

A fqn of a TreeCache node associated with this cache item. This is a node in which data will be kept.

getInterval

public long getInterval()

Specified by:

getInterval in interface CacheItemUser<K,T>

Returns:

Interval at which updates of keys will be executed. Effectively, the interval will be rounded to the nearest multiplicity of the service update thread interval. The interval should be given in milliseconds. If it is 0, the CacheItemDataSource.update(Object, Object) method will be executed on every service thread update (for every key).

setInterval

public void setInterval(long interval)

Specified by:

setInterval in interface CacheItemUser<K,T>

Parameters:

interval - Interval at which the update operation will be executed. Effectively, the interval will be rounded to the nearest multiplicity of the service update thread interval. The interval should be given in milliseconds. If it is 0, the CacheItemDataSource.update(Object, Object) method will be executed on every service thread update (for every key).

getMbeanName

public java.lang.String getMbeanName()

Specified by:

getMbeanName in interface CacheItemUser<K,T>

Returns:

Name of an mbean implementing the RenewableCacheServiceMBean interface, associated with this cache item.

getKeysDuringUpdate

public ConcurrentSet<K> getKeysDuringUpdate()

Specified by:

getKeysDuringUpdate in interface CacheItemUser<K,T>

Returns:

A set of keys, which are currently being updated.

getKeysUpdates

public java.util.concurrent.ConcurrentMap<K,java.lang.Long> getKeysUpdates()

Specified by:

getKeysUpdates in interface CacheItemUser<K,T>

Returns:

A map of keys, which are handeled by this cache item, and corresponding last update times.

getKeysExceptions

public java.util.concurrent.ConcurrentMap<K,java.lang.Throwable> getKeysExceptions()

Specified by:

getKeysExceptions in interface CacheItemUser<K,T>

Returns:

A map of keys, in which an exception occured during an update.

getId

public int getId()

Specified by:

getId in interface CacheItemUser<K,T>

Returns:

A unique id of this instance of cache item.

getInfo

public java.lang.String getInfo()

Specified by:

getInfo in interface CacheItemUser<K,T>

Returns:

Additional information about the state of a data source for this cache item. Returns CacheItemDataSource.getInfo().

getName

public java.lang.String getName()

Specified by:

getName in interface CacheItemUser<K,T>

Returns:

Name of this CacheItem --- the fully qualified name of the class implementing CacheItemDataSource.

get

public final T get(K key)

Description copied from interface: CacheItemUser

Gets an object that is bound to the given key in the associated TreeCache node. If this object is not in the cache, it will be initialized (using the CacheItemDataSource.init(Object) method of a data source that was passed to create(CacheItemDataSource)).

Specified by:

get in interface CacheItemUser<K,T>

Parameters:

key - Key of the object to get.

Returns:

Value of the object.

update

public void update()

Description copied from interface: CacheItemOperations

Called by the service update thread to update all keys and associated values. You shouldn't call it from inside your code.

Specified by:

update in interface CacheItemOperations<K,T>

resetKey

public void resetKey(java.lang.Object key)

Description copied from interface: CacheItemUser

Resets the given key, that is, it's update status. Hence, if a thread updating a key locks for some reason, it is possible to resume updates of this key. Use with caution.

Specified by:

resetKey in interface CacheItemUser<K,T>

Parameters:

key - Key, which update status should be reset.

reportUpdateOk

public void reportUpdateOk(K key)

Description copied from interface: CacheItemOperations

Reports that an update of a key ended wihtout any exceptions.

Specified by:

reportUpdateOk in interface CacheItemOperations<K,T>

Parameters:

key - Key which has been updated.

reportUpdateWithException

public void reportUpdateWithException(K key,
                                      java.lang.Throwable t)

Description copied from interface: CacheItemOperations

Reports that an update of a key ended with an exception.

Specified by:

reportUpdateWithException in interface CacheItemOperations<K,T>

Parameters:

key - Key which has been updated.

t - Exception which was thrown during the update.