org.jivesoftware.smack.util

Class Cache<K,V>

java.lang.Object

org.jivesoftware.smack.util.Cache<K,V>

All Implemented Interfaces:

Map<K,V>

public class Cache<K,V>
extends Object
implements Map<K,V>

A specialized Map that is size-limited (using an LRU algorithm) and has an optional expiration time for cache items. The Map is thread-safe.

The algorithm for cache is as follows: a HashMap is maintained for fast object lookup. Two linked lists are maintained: one keeps objects in the order they are accessed from cache, the other keeps objects in the order they were originally added to cache. When objects are added to cache, they are first wrapped by a CacheObject which maintains the following pieces of information:

• A pointer to the node in the linked list that maintains accessed order for the object. Keeping a reference to the node lets us avoid linear scans of the linked list.
• A pointer to the node in the linked list that maintains the age of the object in cache. Keeping a reference to the node lets us avoid linear scans of the linked list.

To get an object from cache, a hash lookup is performed to get a reference to the CacheObject that wraps the real object we are looking for. The object is subsequently moved to the front of the accessed linked list and any necessary cache cleanups are performed. Cache deletion and expiration is performed as needed.

Author:

Matt Tucker

Nested Class Summary

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

Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
protected org.jivesoftware.smack.util.Cache.LinkedList	ageList Linked list to maintain time that cache objects were initially added to the cache, most recently added to oldest added.
protected long	cacheHits Maintain the number of cache hits and misses.
protected long	cacheMisses Maintain the number of cache hits and misses.
protected org.jivesoftware.smack.util.Cache.LinkedList	lastAccessedList Linked list to maintain order that cache objects are accessed in, most used to least used.
protected Map<K,org.jivesoftware.smack.util.Cache.CacheObject<V>>	map The map the keys and values are stored in.
protected int	maxCacheSize Maximum number of items the cache will hold.
protected long	maxLifetime Maximum length of time objects can exist in cache before expiring.

Constructor Summary

Constructors

Constructor and Description
Cache(int maxSize, long maxLifetime) Create a new cache and specify the maximum size of for the cache in bytes, and the maximum lifetime of objects.

Method Summary

Methods

Modifier and Type	Method and Description
void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
protected void	cullCache() Removes the least recently used elements if the cache size is greater than or equal to the maximum allowed size until the cache is at least 10% empty.
protected void	deleteExpiredEntries() Clears all entries out of cache where the entries are older than the maximum defined age.
Set<Map.Entry<K,V>>	entrySet()
V	get(Object key)
long	getCacheHits()
long	getCacheMisses()
int	getMaxCacheSize()
long	getMaxLifetime()
boolean	isEmpty()
Set<K>	keySet()
V	put(K key, V value)
void	putAll(Map<? extends K,? extends V> map)
V	remove(Object key)
V	remove(Object key, boolean internal)
void	setMaxCacheSize(int maxCacheSize)
void	setMaxLifetime(long maxLifetime)
int	size()
Collection<V>	values()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode

Field Detail

map

protected Map<K,org.jivesoftware.smack.util.Cache.CacheObject<V>> map

The map the keys and values are stored in.

lastAccessedList

protected org.jivesoftware.smack.util.Cache.LinkedList lastAccessedList

Linked list to maintain order that cache objects are accessed in, most used to least used.

ageList

protected org.jivesoftware.smack.util.Cache.LinkedList ageList

Linked list to maintain time that cache objects were initially added to the cache, most recently added to oldest added.

maxCacheSize

protected int maxCacheSize

Maximum number of items the cache will hold.

maxLifetime

protected long maxLifetime

Maximum length of time objects can exist in cache before expiring.

cacheHits

protected long cacheHits

Maintain the number of cache hits and misses. A cache hit occurs every time the get method is called and the cache contains the requested object. A cache miss represents the opposite occurence.

Keeping track of cache hits and misses lets one measure how efficient the cache is; the higher the percentage of hits, the more efficient.

cacheMisses

protected long cacheMisses

Maintain the number of cache hits and misses. A cache hit occurs every time the get method is called and the cache contains the requested object. A cache miss represents the opposite occurence.

Keeping track of cache hits and misses lets one measure how efficient the cache is; the higher the percentage of hits, the more efficient.

Constructor Detail

Cache

public Cache(int maxSize,
     long maxLifetime)

Create a new cache and specify the maximum size of for the cache in bytes, and the maximum lifetime of objects.

Parameters:

maxSize - the maximum number of objects the cache will hold. -1 means the cache has no max size.

maxLifetime - the maximum amount of time (in ms) objects can exist in cache before being deleted. -1 means objects never expire.

Method Detail

put

public V put(K key,
    V value)

Specified by:

put in interface Map<K,V>

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

remove

public V remove(Object key,
       boolean internal)

clear

public void clear()

Specified by:

clear in interface Map<K,V>

size

public int size()

Specified by:

size in interface Map<K,V>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

values

public Collection<V> values()

Specified by:

values in interface Map<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

putAll

public void putAll(Map<? extends K,? extends V> map)

Specified by:

putAll in interface Map<K,V>

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

entrySet

public Set<Map.Entry<K,V>> entrySet()

Specified by:

entrySet in interface Map<K,V>

keySet

public Set<K> keySet()

Specified by:

keySet in interface Map<K,V>

getCacheHits

public long getCacheHits()

getCacheMisses

public long getCacheMisses()

getMaxCacheSize

public int getMaxCacheSize()

setMaxCacheSize

public void setMaxCacheSize(int maxCacheSize)

getMaxLifetime

public long getMaxLifetime()

setMaxLifetime

public void setMaxLifetime(long maxLifetime)

deleteExpiredEntries

protected void deleteExpiredEntries()

Clears all entries out of cache where the entries are older than the maximum defined age.

cullCache

protected void cullCache()

Removes the least recently used elements if the cache size is greater than or equal to the maximum allowed size until the cache is at least 10% empty.