org.norther.tammi.acorn.cache
Interface CachedMap

All Superinterfaces:

ConcurrentMap, Map

All Known Subinterfaces:

Cache, ResourceCache, SessionManager, SharedCache

All Known Implementing Classes:

CachedMapAdapter, DefaultCache, DefaultResourceCache, DefaultSessionManager, DefaultSharedCache

public interface CachedMap
extends ConcurrentMap

Extends the Map interface to support expiration of old entries. The map has a default expiration time, which is used for objects put into the map without an explicit expiration frequency. The maximum expiration time specifies the longest possible expiration time for the map. Its value may affect the performance of the map and should be realistic. Expired entries are searched at regular intervals specified by the expiration sleep interval. All times are given in seconds. The value -1 indicates always infinite time.

The expiration time of an entry is automatically refreshed when it is got from the map if not explicitly declined. However, iterators do not need to refresh entries accessed through them.

The maximum number of entries accepted by the map can be specified with max entries. The oldest entries above the limit will be expired indepently on their expiration time. The limit need not to be strict during puts but maintained by the expiration handler.

Note that the size of the map and its sets and collections is not constant in time as entries expire dynamically. Iterators can return expired entries if there is a pause between calls to the hasNext and next methods.

Author:

Ilkka Priha

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

boolean	add(Object key, Object obj) Adds a cachable object into the map but only if the specified key is not already mapped.
boolean	add(Object key, Object obj, int freq) Adds a cachable object into the map with an object specific expiration frequency but only if the specified key is not already mapped.
Object	expire(Object key) Expires and removes an entry.
void	expireAll() Expires all entries.
void	expireFraction(float fraction) Expires a fraction of entries.
Object	get(Object key, int freq) Gets an object from the map and refreshes it with a specific expiration frequency.
int	getDefaultExpirationTime() Gets the default expiration time in seconds.
int	getExpirationLimit() Gets the expiration limit for the number of cached entries.
int	getExpirationSleepInterval() Gets the expiration sleep interval in seconds.
float	getExpirationThreshold() Gets the threshold relative to the entry limit before expiration of excessive entries starts.
int	getMaxExpirationTime() Gets the maximum expiration time in seconds.
boolean	isAllowExpired() Gets the allow expired option.
boolean	isAutoRefreshDeclined() Gets the automatic refresh declined option.
boolean	isDiscardOverloaded() Gets the discard overloaded option.
Object	put(Object key, Object obj, int freq) Puts a cachable object into the map with an object specific expiration frequency.
Object	putIfAbsent(Object key, Object obj, int freq) Puts a cachable object into the map with an object specific expiration frequency but only if the specified key is not already mapped.
boolean	refresh(Object key) Refreshes an entry.
boolean	refresh(Object key, int freq) Refreshes an entry with a new frequency.
void	setAllowExpired(boolean flag) Sets the allow expired option allowing gets of entries already expired but not yet removed by the expiration handler.
void	setAutoRefreshDeclined(boolean flag) Sets the automatic refresh declined option preventing cached entries being automatically refreshed during plain gets.
void	setDefaultExpirationTime(int t) Sets the default expiration time in seconds.
void	setDiscardOverloaded(boolean flag) Sets the discard overloaded option.
void	setExpirationLimit(int c) Sets the expiration limit for the number of cached entries.
void	setExpirationSleepInterval(int t) Sets the expiration sleep interval in seconds.
void	setExpirationThreshold(float h) Sets the threshold relative to the entry limit before expiration of excessive entries starts.
void	setMaxExpirationTime(int t) Sets the maximum expiration time in seconds.

Methods inherited from interface java.util.concurrent.ConcurrentMap

putIfAbsent, remove, replace, replace

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Method Detail

isAllowExpired

boolean isAllowExpired()

Gets the allow expired option.

Returns:

the allow expired option.

setAllowExpired

void setAllowExpired(boolean flag)

Sets the allow expired option allowing gets of entries already expired but not yet removed by the expiration handler.

Parameters:

flag - the allow expired option.

isDiscardOverloaded

boolean isDiscardOverloaded()

Gets the discard overloaded option.

Returns:

true if new puts are discarded if overloaded, false otherwise.

setDiscardOverloaded

void setDiscardOverloaded(boolean flag)

Sets the discard overloaded option. If set to true, new entries are discarded and an exception thrown when the capacity of the cache is exceeded. The default policy is to expire old entries until enough capacity is available.

Parameters:

flag - true if new puts are discarded if overloaded, false otherwise.

isAutoRefreshDeclined

boolean isAutoRefreshDeclined()

Gets the automatic refresh declined option.

Returns:

the automatic refresh declined option.

setAutoRefreshDeclined

void setAutoRefreshDeclined(boolean flag)

Sets the automatic refresh declined option preventing cached entries being automatically refreshed during plain gets.

Parameters:

flag - the automatic refresh declined option.

getMaxExpirationTime

int getMaxExpirationTime()

Gets the maximum expiration time in seconds.

Returns:

the secs.

setMaxExpirationTime

void setMaxExpirationTime(int t)

Sets the maximum expiration time in seconds.

Parameters:

t - the secs.

getDefaultExpirationTime

int getDefaultExpirationTime()

Gets the default expiration time in seconds.

Returns:

the secs.

setDefaultExpirationTime

void setDefaultExpirationTime(int t)

Sets the default expiration time in seconds.

Parameters:

t - the secs.

getExpirationSleepInterval

int getExpirationSleepInterval()

Gets the expiration sleep interval in seconds.

Returns:

the secs.

setExpirationSleepInterval

void setExpirationSleepInterval(int t)

Sets the expiration sleep interval in seconds.

Parameters:

t - the secs

getExpirationLimit

int getExpirationLimit()

Gets the expiration limit for the number of cached entries.

Returns:

the expiration limit.

setExpirationLimit

void setExpirationLimit(int c)

Sets the expiration limit for the number of cached entries.

Parameters:

c - the expiration limit.

getExpirationThreshold

float getExpirationThreshold()

Gets the threshold relative to the entry limit before expiration of excessive entries starts.

Returns:

the threshold.

setExpirationThreshold

void setExpirationThreshold(float h)

Sets the threshold relative to the entry limit before expiration of excessive entries starts. Values below 1.0 define the filling rate right after expiration and values above 1.0 define the filling rate just before expiration. The exact value 1.0 is not recommended as it starts expiration after every addition of entries when the filling rate is at the limit.

Parameters:

h - the threshold.

add

boolean add(Object key,
            Object obj)

Adds a cachable object into the map but only if the specified key is not already mapped.

Parameters:

key - a key.

obj - an object.

Returns:

true if added, false otherwise.

Throws:

IllegalStateException - if capacity is full and overload not allowed.

get

Object get(Object key,
           int freq)

Gets an object from the map and refreshes it with a specific expiration frequency.

Parameters:

key - a key.

freq - an expiration frequency.

Returns:

the value of the key.

put

Object put(Object key,
           Object obj,
           int freq)

Puts a cachable object into the map with an object specific expiration frequency.

Parameters:

key - a key.

obj - an object.

freq - an expiration frequency.

Returns:

the previous value of the key.

Throws:

IllegalStateException - if capacity is full and overload not allowed.

putIfAbsent

Object putIfAbsent(Object key,
                   Object obj,
                   int freq)

Puts a cachable object into the map with an object specific expiration frequency but only if the specified key is not already mapped.

Parameters:

key - a key.

obj - an object.

freq - an expiration frequency.

Returns:

the previous value of the key.

Throws:

IllegalStateException - if capacity is full and overload not allowed.

add

boolean add(Object key,
            Object obj,
            int freq)

Adds a cachable object into the map with an object specific expiration frequency but only if the specified key is not already mapped.

Parameters:

key - a key.

obj - an object.

freq - an expiration frequency.

Returns:

true if added, false otherwise.

Throws:

IllegalStateException - if capacity is full and overload not allowed.

refresh

boolean refresh(Object key)

Refreshes an entry.

Parameters:

key - a key.

Returns:

true if refreshed, otherwise false.

refresh

boolean refresh(Object key,
                int freq)

Refreshes an entry with a new frequency.

Parameters:

key - a key.

freq - an expiration frequency.

Returns:

true if refreshed, otherwise false.

expire

Object expire(Object key)

Expires and removes an entry.

Parameters:

key - the key.

Returns:

the expired value or null.

expireAll

void expireAll()

Expires all entries.

expireFraction

void expireFraction(float fraction)

Expires a fraction of entries.

Parameters:

fraction - the fraction to expire (0.0..1.0).

Throws:

IllegalArgumentException - for an invalid fragment.