Cache (n-orm core 0.0.1-SNAPSHOT API)

java.lang.Object
- com.googlecode.n_orm.cache.perthread.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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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).
`protected boolean`	`isActive()` Whether this cache actually caches.
`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.
`protected void`	`setActive(boolean active)` Making it possible to disable this cache for test purpose.
`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.
`void`	`unregister(String fullIdentifier)` Removes an element in the cache given by its full identifier.

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.
  - isActive
```
protected boolean isActive()
```
    Whether this cache actually caches.
  - setActive
```
protected void setActive(boolean active)
```
    Making it possible to disable this cache for test purpose. Usage in production is strongly discouraged.
    
    Parameters:
    
    active -
  - 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
  - unregister
```
public void unregister(String fullIdentifier)
                throws IllegalStateException
```
    Removes an element in the cache given by 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 id of 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.
  - 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

Class Cache

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getTimeToLiveSeconds

setTimeToLiveSeconds

getMaxElementsInCache

setMaxElementsInCache

getPeriodBetweenCacheCleanupMS

setPeriodBetweenCacheCleanupMS

findCache

getCache

getThreadId

isActive

setActive

checkState

register

unregister

unregister

getKnownPersistingElement

getKnownPersistingElement

size

reset

isClosed

close

finalize