org.apache.shiro.util
Class SoftHashMap<K,V>

java.lang.Object
  org.apache.shiro.util.SoftHashMap<K,V>

All Implemented Interfaces:

Map<K,V>

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

A SoftHashMap is a memory-constrained map that stores its values in SoftReferences. (Contrast this with the JDK's WeakHashMap, which uses weak references for its keys, which is of little value if you want the cache to auto-resize itself based on memory constraints).

Having the values wrapped by soft references allows the cache to automatically reduce its size based on memory limitations and garbage collection. This ensures that the cache will not cause memory leaks by holding strong references to all of its values.

This class is a generics-enabled Map based on initial ideas from Heinz Kabutz's and Sydney Redelinghuys's publicly posted version (with their approval), with continued modifications.

This implementation is thread-safe and usable in concurrent environments.

Since:

1.0

Nested Class Summary

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

Map.Entry<K,V>

Constructor Summary

SoftHashMap()
Creates a new SoftHashMap with a default retention size size of DEFAULT_RETENTION_SIZE (100 entries).

SoftHashMap(int retentionSize)
Creates a new SoftHashMap with the specified retention size.

SoftHashMap(Map<K,V> source)
Creates a SoftHashMap backed by the specified source, with a default retention size of DEFAULT_RETENTION_SIZE (100 entries).

SoftHashMap(Map<K,V> source, int retentionSize)
Creates a SoftHashMap backed by the specified source, with the specified retention size.

Method Summary

void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
Set<Map.Entry<K,V>>	entrySet()
V	get(Object key)
boolean	isEmpty()
Set<K>	keySet()
V	put(K key, V value) Creates a new entry, but wraps the value in a SoftValue instance to enable auto garbage collection.
void	putAll(Map<? extends K,? extends V> m)
V	remove(Object key)
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

Constructor Detail

SoftHashMap

public SoftHashMap()

Creates a new SoftHashMap with a default retention size size of DEFAULT_RETENTION_SIZE (100 entries).

See Also:

SoftHashMap(int)

SoftHashMap

public SoftHashMap(int retentionSize)

Creates a new SoftHashMap with the specified retention size.

The retention size (n) is the total number of most recent entries in the map that will be strongly referenced (ie 'retained') to prevent them from being eagerly garbage collected. That is, the point of a SoftHashMap is to allow the garbage collector to remove as many entries from this map as it desires, but there will always be (n) elements retained after a GC due to the strong references.

Note that in a highly concurrent environments the exact total number of strong references may differ slightly than the actual retentionSize value. This number is intended to be a best-effort retention low water mark.

Parameters:

retentionSize - the total number of most recent entries in the map that will be strongly referenced (retained), preventing them from being eagerly garbage collected by the JVM.

SoftHashMap

public SoftHashMap(Map<K,V> source)

Creates a SoftHashMap backed by the specified source, with a default retention size of DEFAULT_RETENTION_SIZE (100 entries).

Parameters:

source - the backing map to populate this SoftHashMap

See Also:

SoftHashMap(Map,int)

SoftHashMap

public SoftHashMap(Map<K,V> source,
                   int retentionSize)

Creates a SoftHashMap backed by the specified source, with the specified retention size.

The retention size (n) is the total number of most recent entries in the map that will be strongly referenced (ie 'retained') to prevent them from being eagerly garbage collected. That is, the point of a SoftHashMap is to allow the garbage collector to remove as many entries from this map as it desires, but there will always be (n) elements retained after a GC due to the strong references.

Note that in a highly concurrent environments the exact total number of strong references may differ slightly than the actual retentionSize value. This number is intended to be a best-effort retention low water mark.

Parameters:

source - the backing map to populate this SoftHashMap

retentionSize - the total number of most recent entries in the map that will be strongly referenced (retained), preventing them from being eagerly garbage collected by the JVM.

Method Detail

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

putAll

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

Specified by:

putAll in interface Map<K,V>

keySet

public Set<K> keySet()

Specified by:

keySet in interface Map<K,V>

values

public Collection<V> values()

Specified by:

values in interface Map<K,V>

put

public V put(K key,
             V value)

Creates a new entry, but wraps the value in a SoftValue instance to enable auto garbage collection.

Specified by:

put in interface Map<K,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

clear

public void clear()

Specified by:

clear in interface Map<K,V>

size

public int size()

Specified by:

size in interface Map<K,V>

entrySet

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

Specified by:

entrySet in interface Map<K,V>