com.googlecode.n_orm.cache
Class Cache

java.lang.Object
  com.googlecode.n_orm.cache.Cache

public class Cache
extends Object

A cache for temporarily storing PersistingElements.
There is a cache per thread, so that cached elements are thread safe unless explicitly shared across threads. Only thread owning a cache is allowed to use this cache.
To get a cache, use getCache() within the using thread.
Caches are limited in size (see getMaxElementsInCache()). Cached elements are removed as soon as they have not been accessed since a certain amount of time (see getTimeToLiveSeconds()).
Caches for dead thread are recycled, but in case they have not been used during a certain amount of time (see getTimeToLiveSeconds()), they are dropped.

Author:

fondemen

Method Summary

protected void	checkState()
protected void	close() Closes the cache.
protected void	finalize()
static Cache	findCache(Thread thread)
static Cache	getCache() Gives a cache to the current thread.
PersistingElement	getKnownPersistingElement(String fullIdentifier) Finds an element in the cache according to its full identifier.
PersistingElement	getKnownPersistingElement(String identifier, Class<? extends PersistingElement> clazz) Finds an element in the cache according to its identifier.
static int	getMaxElementsInCache() The maximum number of elements that can be kept in a (per-thread) cache (10 000 by default).
static int	getPeriodBetweenCacheCleanupMS() The time between two cache cleanups (1s by default).
static String	getThreadId(Thread thread) A string identifier for the thread.
static int	getTimeToLiveSeconds() Time during which a element is kept in the cache (10s by default).
boolean	isClosed() Checks if this cache can be used or not.
void	register(PersistingElement element) Registers an element in the cache.
void	reset() Clears the cache.
static void	setMaxElementsInCache(int maxElementsInCache) Sets the maximum number of elements that can be kept in a (per-thread) cache.
static void	setPeriodBetweenCacheCleanupMS(int periodBetweenCacheCleanupMS) The time between two cache cleanups.
static void	setTimeToLiveSeconds(int timeToLiveSeconds) Sets time during which a element is kept in the cache.
int	size() The size of the cache.
void	unregister(PersistingElement element) Removes an element in the cache.

Methods inherited from class java.lang.Object

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

Method Detail

getTimeToLiveSeconds

public static int getTimeToLiveSeconds()

Time during which a element is kept in the cache (10s by default). If an element is accessed (e.g. by storing or activating it), its time to live is reseted. A cache is also kept during this time once its corresponding thread is over, so that it can be reused by another thread.

Returns:

time to live in seconds

setTimeToLiveSeconds

public static void setTimeToLiveSeconds(int timeToLiveSeconds)

Sets time during which a element is kept in the cache. If an element is accessed (e.g. by storing or activating it), its time to live is reseted. A cache is also kept during this time once its corresponding thread is over, so that it can be reused by another thread.

Parameters:

timeToLiveSeconds - time to live in seconds

getMaxElementsInCache

public static int getMaxElementsInCache()

The maximum number of elements that can be kept in a (per-thread) cache (10 000 by default).

setMaxElementsInCache

public static void setMaxElementsInCache(int maxElementsInCache)

Sets the maximum number of elements that can be kept in a (per-thread) cache.

getPeriodBetweenCacheCleanupMS

public static int getPeriodBetweenCacheCleanupMS()

The time between two cache cleanups (1s by default). Caches with alive thread are asked to cleanup at next access: all elements that have not been accessed since their time to live are discarded. Caches with dead threads are checked for time to live and discarded if this period is over, otherwise their elements are immediately checked for time to live.

Returns:

period between two cache cleanups in milliseconds

setPeriodBetweenCacheCleanupMS

public static void setPeriodBetweenCacheCleanupMS(int periodBetweenCacheCleanupMS)

The time between two cache cleanups. Caches with alive thread are asked to cleanup at next access: all elements that have not been accessed since their time to live are discarded. Caches with dead threads are checked for time to live and discarded if this period is over, otherwise their elements are immediately checked for time to live.

Parameters:

periodBetweenCacheCleanupMS - period between two cache cleanups in milliseconds

findCache

public static Cache findCache(Thread thread)

getCache

public static Cache getCache()

Gives a cache to the current thread. In case this cache does not already exists, creates it.

getThreadId

public static String getThreadId(Thread thread)

A string identifier for the thread.

checkState

protected void checkState()

register

public void register(PersistingElement element)
              throws IllegalStateException

Registers an element in the cache.
Only thread for this cache has access to this method.
In case this cache is marked for cleanup, elements are checked for their time to live (see setTimeToLiveSeconds(int)).
In case the maximum number of cacheable elements is reached, element with the eldest access id removed from the cache (see setMaxElementsInCache(int))

Parameters:

element - the element to be cached (during getTimeToLiveSeconds())

Throws:

IllegalStateException - in case this thread is not the thread for this cache

unregister

public void unregister(PersistingElement element)
                throws IllegalStateException

Removes an element in the cache.
Only thread for this cache has access to this method.
In case this cache is marked for cleanup, elements are checked for their time to live (see setTimeToLiveSeconds(int)).

Parameters:

element - the element to be uncached

Throws:

IllegalStateException - in case this thread is not the thread for this cache

getKnownPersistingElement

public PersistingElement getKnownPersistingElement(String fullIdentifier)

Finds an element in the cache according to its full identifier.
Only thread for this cache has access to this method.
In case this cache is marked for cleanup, elements are checked for their time to live (see setTimeToLiveSeconds(int)).

Parameters:

fullIdentifier - the full identifier of the element to be cached; null if not found

Throws:

IllegalStateException - in case this thread is not the thread for this cache

See Also:

PersistingElement.getFullIdentifier()

getKnownPersistingElement

public PersistingElement getKnownPersistingElement(String identifier,
                                                   Class<? extends PersistingElement> clazz)

Finds an element in the cache according to its identifier.
Only thread for this cache has access to this method.
In case this cache is marked for cleanup, elements are checked for their time to live (see setTimeToLiveSeconds(int)).

Parameters:

identifier - the full identifier of the element to be cached; null if not found

clazz - the class that the element instantiates (see Object#getClass()); null if not found

Throws:

IllegalStateException - in case this thread is not the thread for this cache

See Also:

PersistingElement.getIdentifier()

size

public int size()

The size of the cache. This method checks elements for their time to live regardless the cache is marked for that or not.

Returns:

reset

public void reset()

Clears the cache.

isClosed

public boolean isClosed()

Checks if this cache can be used or not. A cache cannot be used if its thread is dead and if its time to live is over. A closed cache must not be used in any case (necessary resources were released)

Returns:

whether this cache has bee closed

See Also:

close()

close

protected void close()

Closes the cache. This method is automatically invoked on caches for dead threads and whose time to live is over. A closed cache cannot be used anymore.

See Also:

isClosed()

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable