org.zkoss.util
Class CacheMap

java.lang.Object
  org.zkoss.util.CacheMap

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Map

Direct Known Subclasses:

ResourceCache

public class CacheMap
extends java.lang.Object
implements java.util.Map, java.io.Serializable, java.lang.Cloneable

The cache map. The key-to-value mappings hold in this map is temporary. They are removed when GC demanding memory and a criteria is met. The criteria is whether the mapping is old enough (called lifetime), or the upper bound is hit (called max-size).

The criteria can be changed by overriding canExpunge(org.zkoss.util.CacheMap.Value). When to check the criteria can be changed by overriding shallExpunge().

If the criteria is totally independent of GC, you could override newQueue() to return null. Then, shallExpunge() always returns true (rather than when GC is activated) -- of course, you could override shallExpunge(), too.

The constructor doesn't provide parameter to set the lifetime or maxsize. However, setLifetime(int) and setMaxSize(int) return the map, so you can do:
Map map = new CacheMap().setLifetime(10000);

It is very different from WeakHashMap:

• The mapping might be removed even if the key is hold somewhere (i.e., strong reachable).
• The mapping might not be removed when GC demanding memory if the criteria doesn't meet.
• It is not serializable.

Like other maps, it is not thread-safe. To get one, use java.util.Collections.synchronizedMap.

Implementation Note: there is another version of CacheMap that uses WeakReference for each value (refer to obsolete). The drawback is that all mapping will be queued and need to be examined, because GC tends to release all reference at once.

We don't use PhantomReference because it is still required to re-create the reference after enqueued.

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

protected static class

CacheMap.Value The class to hold key/value.

Field Summary

static int	DEFAULT_LIFETIME The default minimal lifetime, unit=milliseconds.
static int	DEFAULT_MAXSIZE The default maximal allowed size.
protected static int	EXPUNGE_CONTINUE Returns by canExpunge(org.zkoss.util.CacheMap.Value) to denote the searching of the next mapping shall continue.
protected static int	EXPUNGE_NO Returns by canExpunge(org.zkoss.util.CacheMap.Value) to denote it shall not be expunged.
protected static int	EXPUNGE_STOP Returns by canExpunge(org.zkoss.util.CacheMap.Value) to denote the searching of the next mapping shall stop.
protected static int	EXPUNGE_YES Returns by canExpunge(org.zkoss.util.CacheMap.Value) to denote it shall be expunged.

Constructor Summary

CacheMap()
Constructs a cachemap by using LinkedHashMap internally.

CacheMap(int cap)
Constructs a cachemap by using LinkedHashMap internally.

CacheMap(int cap, float load)
Constructs a cachemap by using LinkedHashMap internally.

Method Summary

protected int	canExpunge(CacheMap.Value v) Tests whether certain value is OK to expunge.
void	clear()
java.lang.Object	clone() To make sure that it is in the acess order.
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
java.util.Set	entrySet()
boolean	equals(java.lang.Object o)
java.lang.Object	get(java.lang.Object key)
int	getLifetime() Gets the minimal lifetime, unit=milliseconds.
int	getMaxSize() Gets the maximal allowed size.
java.lang.Object	getWithoutExpunge(java.lang.Object key) Returns the value without trying to expunge first.
int	hashCode()
boolean	isEmpty() Gets the last accessed time, in system millisecs.
java.util.Set	keySet()
protected java.lang.ref.ReferenceQueue	newQueue() Creates the reference queue.
protected void	onExpunge(CacheMap.Value v) Called when a pair of key and value having been expunged.
java.lang.Object	put(java.lang.Object key, java.lang.Object value)
void	putAll(java.util.Map map)
java.lang.Object	remove(java.lang.Object key)
CacheMap	setLifetime(int lifetime) Sets the minimal lifetime.
CacheMap	setMaxSize(int maxsize) Sets the maximal allowed size.
protected boolean	shallExpunge() Returns whether it is time to expunge.
int	size()
java.lang.String	toString()
java.util.Collection	values()

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_LIFETIME

public static final int DEFAULT_LIFETIME

The default minimal lifetime, unit=milliseconds. It is 30 minutes.

See Also:

Constant Field Values

DEFAULT_MAXSIZE

public static final int DEFAULT_MAXSIZE

The default maximal allowed size. It is 1024.

See Also:

Constant Field Values

EXPUNGE_NO

protected static final int EXPUNGE_NO

Returns by canExpunge(org.zkoss.util.CacheMap.Value) to denote it shall not be expunged.

See Also:

Constant Field Values

EXPUNGE_YES

protected static final int EXPUNGE_YES

Returns by canExpunge(org.zkoss.util.CacheMap.Value) to denote it shall be expunged.

See Also:

Constant Field Values

EXPUNGE_CONTINUE

protected static final int EXPUNGE_CONTINUE

Returns by canExpunge(org.zkoss.util.CacheMap.Value) to denote the searching of the next mapping shall continue.

See Also:

Constant Field Values

EXPUNGE_STOP

protected static final int EXPUNGE_STOP

Returns by canExpunge(org.zkoss.util.CacheMap.Value) to denote the searching of the next mapping shall stop.

See Also:

Constant Field Values

Constructor Detail

CacheMap

public CacheMap()

Constructs a cachemap by using LinkedHashMap internally.

CacheMap

public CacheMap(int cap)

Constructs a cachemap by using LinkedHashMap internally.

CacheMap

public CacheMap(int cap,
                float load)

Constructs a cachemap by using LinkedHashMap internally.

Method Detail

onExpunge

protected void onExpunge(CacheMap.Value v)

Called when a pair of key and value having been expunged. This method is called after it is removed, so you could add it back.

Default: does nothing

shallExpunge

protected boolean shallExpunge()

Returns whether it is time to expunge. Once shallExpunge returns true, values are examined one-by-one thru canExpunge(org.zkoss.util.CacheMap.Value), and expunged if EXPUNGE_YES.

This implementation returns true only if newQueue() returns null (in constructor) or GC was activated. You might override it to enforce expunge besides GC.

See Also:

canExpunge(org.zkoss.util.CacheMap.Value)

canExpunge

protected int canExpunge(CacheMap.Value v)

Tests whether certain value is OK to expunge.

Note: values are tested thru canExpunge(org.zkoss.util.CacheMap.Value) only if shallExpunge() returns true.

Deriving classes might override this method to return different value for different criteria.

The return value coulde be a combination of EXPUNGE_xxx. One of EXPUNGE_YES and EXPUNGE_NO is returned to denote whether to expunge the mapping. One of EXPUNGE_CONTINUE and EXPUNGE_STOP is returned to denote whether to continue the searching of the next mapping for expunging.

Normally, you return either (EXPUNGE_YES|EXPUNGE_CONTINUE) or (EXPUNG_NO|EXPUNGE_STOP). Notice that the mapping is queried in the last-access order. Thus, you rarely needs to return (EXPUNGE_NO|EXPUNGE_CONTINUE) unless the appropriate one might be out of this order.

This implementation compares the access time and size. It returns (EXPUNGE_YES|EXPUNGE_CONTINUE) if OK, and (EXPUNGE_NO|EXPUNGE_STOP) if not.

Returns:

a combination of EXPUNGE_xxx

See Also:

shallExpunge()

newQueue

protected java.lang.ref.ReferenceQueue newQueue()

Creates the reference queue. It is called only once in the constructor (so it is meaningless to change the returned value after constructed).

Default: new ReferenceQueue();
Override this method to return null if you want to expunge items every time get(java.lang.Object) or put(java.lang.Object, java.lang.Object) is called -- not only GC is activated. In other words, if newQueue() returns null, shallExpunge() always returns true (unless you override it too).

getLifetime

public int getLifetime()

Gets the minimal lifetime, unit=milliseconds. An mapping won't be removed by GC unless the minimal lifetime or the maximal allowed size exceeds.

See Also:

getMaxSize()

setLifetime

public CacheMap setLifetime(int lifetime)

Sets the minimal lifetime. Default: DEFAULT_LIFETIME.

Parameters:

lifetime - the lifetime, unit=milliseconds; if non-posive, they will be removed immediately.

See Also:

getLifetime()

getMaxSize

public int getMaxSize()

Gets the maximal allowed size. Defalut: DEFAULT_MAXSIZE. An mapping won't be removed by GC unless the minimal lifetime or the maximal allowed size exceeds.

See Also:

getLifetime()

setMaxSize

public CacheMap setMaxSize(int maxsize)

Sets the maximal allowed size.

See Also:

getMaxSize()

isEmpty

public boolean isEmpty()

Gets the last accessed time, in system millisecs.

Specified by:

isEmpty in interface java.util.Map

Returns:

the last accessed time; 0 if not found

size

public int size()

Specified by:

size in interface java.util.Map

clear

public void clear()

Specified by:

clear in interface java.util.Map

remove

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

Specified by:

remove in interface java.util.Map

get

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

Specified by:

get in interface java.util.Map

getWithoutExpunge

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

Returns the value without trying to expunge first. It is useful if you want to preserve all entries.

containsKey

public boolean containsKey(java.lang.Object key)

Specified by:

containsKey in interface java.util.Map

containsValue

public boolean containsValue(java.lang.Object value)

Specified by:

containsValue in interface java.util.Map

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Specified by:

put in interface java.util.Map

putAll

public void putAll(java.util.Map map)

Specified by:

putAll in interface java.util.Map

entrySet

public java.util.Set entrySet()

Specified by:

entrySet in interface java.util.Map

keySet

public java.util.Set keySet()

Specified by:

keySet in interface java.util.Map

values

public java.util.Collection values()

Specified by:

values in interface java.util.Map

hashCode

public int hashCode()

Specified by:

hashCode in interface java.util.Map

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Specified by:

equals in interface java.util.Map

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

clone

public java.lang.Object clone()

To make sure that it is in the acess order.

Overrides:

clone in class java.lang.Object