gnu.java.util

Class WeakIdentityHashMap

Implemented Interfaces:
Map<K,V>

public class WeakIdentityHashMap
extends AbstractMap<K,V>
implements Map<K,V>

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.

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.

See Also:
HashMap, WeakReference, WeakHashMap, IdentityHashMap, LinkedHashMap

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap<K,V>

AbstractMap.SimpleEntry, AbstractMap.SimpleImmutableEntry

Constructor Summary

WeakIdentityHashMap()
Creates a new weak hash map with default load factor and default capacity.
WeakIdentityHashMap(int initialCapacity)
Creates a new weak hash map with default load factor and the given capacity.
WeakIdentityHashMap(int initialCapacity, float loadFactor)
Creates a new weak hash map with the given initial capacity and load factor.
WeakIdentityHashMap(Map<K,V> m)
Construct a new WeakIdentityHashMap with the same mappings as the given map.

Method Summary

void
clear()
Clears all entries from this map.
boolean
containsKey(Object key)
Tells if the map contains the given key.
boolean
containsValue(Object value)
Returns true if the map contains at least one key which points to the specified object as a value.
Set<E>
entrySet()
Returns a set representation of the entries in this map.
Object
get(Object key)
Gets the value the key is mapped to.
boolean
isEmpty()
Tells if the map is empty.
Set<E>
keySet()
Returns a set representation of the keys in this map.
Object
put(Object key, Object value)
Adds a new key/value mapping to this map.
void
putAll(Map<K,V> m)
Puts all of the mappings from the given map into this one.
Object
remove(Object key)
Removes the key and the corresponding value from this map.
int
size()
Returns the size of this hash map.
Collection<E>
values()
Returns a collection representation of the values in this map.

Methods inherited from class java.util.AbstractMap<K,V>

V>> entrySet, clear, clone, containsKey, containsValue, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, toString, values

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

WeakIdentityHashMap

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

WeakIdentityHashMap

public WeakIdentityHashMap(int initialCapacity)
Creates a new weak hash map with default load factor and the given capacity.
Parameters:
initialCapacity - the initial capacity
Throws:
IllegalArgumentException - if initialCapacity is negative

WeakIdentityHashMap

public WeakIdentityHashMap(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:
IllegalArgumentException - if initialCapacity is negative, or loadFactor is non-positive

WeakIdentityHashMap

public WeakIdentityHashMap(Map<K,V> m)
Construct a new WeakIdentityHashMap with the same mappings as the given map. The WeakIdentityHashMap has a default load factor of 0.75.
Parameters:
m - the map to copy
Throws:
NullPointerException - if m is null
Since:
1.3

Method Details

clear

public void clear()
Clears all entries from this map.
Specified by:
clear in interface Map<K,V>
Overrides:
clear in interface AbstractMap<K,V>

containsKey

public boolean containsKey(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 Map<K,V>
Overrides:
containsKey in interface AbstractMap<K,V>
Parameters:
key - the key to look for
Returns:
true, iff the map contains an entry for the given key.

containsValue

public boolean containsValue(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 Map<K,V>
Overrides:
containsValue in interface AbstractMap<K,V>
Parameters:
value - the value to search for
Returns:
true if it is found in the set.

entrySet

public Set<E> 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.
Returns:
a set representation of the entries.

get

public Object get(Object key)
Gets the value the key is mapped to.
Specified by:
get in interface Map<K,V>
Overrides:
get in interface AbstractMap<K,V>
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.

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 Map<K,V>
Overrides:
isEmpty in interface AbstractMap<K,V>
Returns:
true, iff the map is empty.

keySet

public Set<E> 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 Map<K,V>
Overrides:
keySet in interface AbstractMap<K,V>
Returns:
a set representation of the keys.

put

public Object put(Object key,
                  Object value)
Adds a new key/value mapping to this map.
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.

putAll

public void putAll(Map<K,V> 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.
Parameters:
m - the map to copy in

remove

public Object remove(Object key)
Removes the key and the corresponding value from this map.
Specified by:
remove in interface Map<K,V>
Overrides:
remove in interface AbstractMap<K,V>
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.

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 Map<K,V>
Overrides:
size in interface AbstractMap<K,V>
Returns:
the number of entries in this hash map.

values

public Collection<E> 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 Map<K,V>
Overrides:
values in interface AbstractMap<K,V>
Returns:
a collection representation of the values.

WeakIdentityHashMap -- an identity hashtable that keeps only weak references to its keys, allowing the virtual machine to reclaim them Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.