edu.toronto.cs.util
Class SoftHashMap

java.lang.Object
  extended by java.util.AbstractMap
      extended by java.util.HashMap
          extended by edu.toronto.cs.util.SoftHashMap
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.util.Map
Direct Known Subclasses:
SoftSoftHashMap

public class SoftHashMap
extends java.util.HashMap
implements java.util.Map

A weak hash map has only weak references to the key. This means that it allows the key to be garbage collected if it is not used otherwise. If this happens, the entry will eventually disappear from the map, asynchronously.

A weak hash map makes most sense when the keys doesn't override the equals method: If there is no other reference to the key nobody can ever look up the key in this table and so the entry can be removed. This table also works when the equals method is overloaded, such as String keys, but you should be prepared to deal with some entries disappearing spontaneously.

Other strange behaviors to be aware of: The size of this map may spontaneously shrink (even if you use a synchronized map and synchronize it); it behaves as if another thread removes entries from this table without synchronization. The entry set returned by entrySet has similar phenomenons: The size may spontaneously shrink, or an entry, that was in the set before, suddenly disappears.

A weak hash map is not meant for caches; use a normal map, with soft references as values instead, or try LinkedHashMap.

The weak hash map supports null values and null keys. The null key is never deleted from the map (except explictly of course). The performance of the methods are similar to that of a hash map.

The value objects are strongly referenced by this table. So if a value object maintains a strong reference to the key (either direct or indirect) the key will never be removed from this map. According to Sun, this problem may be fixed in a future release. It is not possible to do it with the jdk 1.2 reference model, though.

Since:
1.2
Author:
Jochen Hoenicke, Eric Blake (ebb9@email.byu.edu)
See Also:
HashMap, WeakReference, LinkedHashMap, Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
java.util.Map.Entry
 
Constructor Summary
SoftHashMap()
          Creates a new weak hash map with default load factor and default capacity.
SoftHashMap(int initialCapacity)
          Creates a new weak hash map with default load factor and the given capacity.
SoftHashMap(int initialCapacity, float loadFactor)
          Creates a new weak hash map with the given initial capacity and load factor.
SoftHashMap(java.util.Map m)
          Construct a new WeakHashMap with the same mappings as the given map.
 
Method Summary
 void clear()
          Clears all entries from this map.
 boolean containsKey(java.lang.Object key)
          Tells if the map contains the given key.
 boolean containsValue(java.lang.Object value)
          Returns true if the map contains at least one key which points to the specified object as a value.
 java.util.Set entrySet()
          Returns a set representation of the entries in this map.
 java.lang.Object get(java.lang.Object key)
          Gets the value the key is mapped to.
 boolean isEmpty()
          Tells if the map is empty.
 java.util.Set keySet()
          Returns a set representation of the keys in this map.
 java.lang.Object put(java.lang.Object key, java.lang.Object value)
          Adds a new key/value mapping to this map.
 void putAll(java.util.Map m)
          Puts all of the mappings from the given map into this one.
 java.lang.Object remove(java.lang.Object key)
          Removes the key and the corresponding value from this map.
 int size()
          Returns the size of this hash map.
 java.util.Collection values()
          Returns a collection representation of the values in this map.
 
Methods inherited from class java.util.HashMap
clone
 
Methods inherited from class java.util.AbstractMap
equals, hashCode, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode
 

Constructor Detail

SoftHashMap

public SoftHashMap()
Creates a new weak hash map with default load factor and default capacity.


SoftHashMap

public SoftHashMap(int initialCapacity)
Creates a new weak hash map with default load factor and the given capacity.

Parameters:
initialCapacity - the initial capacity
Throws:
java.lang.IllegalArgumentException - if initialCapacity is negative

SoftHashMap

public SoftHashMap(int initialCapacity,
                   float loadFactor)
Creates a new weak hash map with the given initial capacity and load factor.

Parameters:
initialCapacity - the initial capacity.
loadFactor - the load factor (see class description of HashMap).
Throws:
java.lang.IllegalArgumentException - if initialCapacity is negative, or loadFactor is non-positive

SoftHashMap

public SoftHashMap(java.util.Map m)
Construct a new WeakHashMap with the same mappings as the given map. The WeakHashMap has a default load factor of 0.75.

Parameters:
m - the map to copy
Throws:
java.lang.NullPointerException - if m is null
Since:
1.3
Method Detail

size

public int size()
Returns the size of this hash map. Note that the size() may shrink spontaneously, if the some of the keys were only weakly reachable.

Specified by:
size in interface java.util.Map
Overrides:
size in class java.util.HashMap
Returns:
the number of entries in this hash map.

isEmpty

public boolean isEmpty()
Tells if the map is empty. Note that the result may change spontanously, if all of the keys were only weakly reachable.

Specified by:
isEmpty in interface java.util.Map
Overrides:
isEmpty in class java.util.HashMap
Returns:
true, iff the map is empty.

containsKey

public boolean containsKey(java.lang.Object key)
Tells if the map contains the given key. Note that the result may change spontanously, if the key was only weakly reachable.

Specified by:
containsKey in interface java.util.Map
Overrides:
containsKey in class java.util.HashMap
Parameters:
key - the key to look for
Returns:
true, iff the map contains an entry for the given key.

get

public java.lang.Object get(java.lang.Object key)
Gets the value the key is mapped to.

Specified by:
get in interface java.util.Map
Overrides:
get in class java.util.HashMap
Returns:
the value the key was mapped to. It returns null if the key wasn't in this map, or if the mapped value was explicitly set to null.

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)
Adds a new key/value mapping to this map.

Specified by:
put in interface java.util.Map
Overrides:
put in class java.util.HashMap
Parameters:
key - the key, may be null
value - the value, may be null
Returns:
the value the key was mapped to previously. It returns null if the key wasn't in this map, or if the mapped value was explicitly set to null.

remove

public java.lang.Object remove(java.lang.Object key)
Removes the key and the corresponding value from this map.

Specified by:
remove in interface java.util.Map
Overrides:
remove in class java.util.HashMap
Parameters:
key - the key. This may be null.
Returns:
the value the key was mapped to previously. It returns null if the key wasn't in this map, or if the mapped value was explicitly set to null.

entrySet

public java.util.Set entrySet()
Returns a set representation of the entries in this map. This set will not have strong references to the keys, so they can be silently removed. The returned set has therefore the same strange behaviour (shrinking size(), disappearing entries) as this weak hash map.

Specified by:
entrySet in interface java.util.Map
Overrides:
entrySet in class java.util.HashMap
Returns:
a set representation of the entries.

clear

public void clear()
Clears all entries from this map.

Specified by:
clear in interface java.util.Map
Overrides:
clear in class java.util.HashMap

containsValue

public boolean containsValue(java.lang.Object value)
Returns true if the map contains at least one key which points to the specified object as a value. Note that the result may change spontanously, if its key was only weakly reachable.

Specified by:
containsValue in interface java.util.Map
Overrides:
containsValue in class java.util.HashMap
Parameters:
value - the value to search for
Returns:
true if it is found in the set.

keySet

public java.util.Set keySet()
Returns a set representation of the keys in this map. This set will not have strong references to the keys, so they can be silently removed. The returned set has therefore the same strange behaviour (shrinking size(), disappearing entries) as this weak hash map.

Specified by:
keySet in interface java.util.Map
Overrides:
keySet in class java.util.HashMap
Returns:
a set representation of the keys.

putAll

public void putAll(java.util.Map m)
Puts all of the mappings from the given map into this one. If the key already exists in this map, its value is replaced.

Specified by:
putAll in interface java.util.Map
Overrides:
putAll in class java.util.HashMap
Parameters:
m - the map to copy in

values

public java.util.Collection values()
Returns a collection representation of the values in this map. This collection will not have strong references to the keys, so mappings can be silently removed. The returned collection has therefore the same strange behaviour (shrinking size(), disappearing entries) as this weak hash map.

Specified by:
values in interface java.util.Map
Overrides:
values in class java.util.HashMap
Returns:
a collection representation of the values.