org.jomc.util
Class WeakIdentityHashMap<K,V>

Package class diagram package WeakIdentityHashMap
java.lang.Object
  extended by org.jomc.util.WeakIdentityHashMap<K,V>
Type Parameters:
K - The type of keys maintained by this map.
V - The type of mapped values.
All Implemented Interfaces:
Map<K,V>

public final class WeakIdentityHashMap<K,V>
extends Object
implements Map<K,V>

Hash-table based Map implementation with weak keys, using object-identity in place of object-equality when comparing keys.

In a WeakIdentityHashMap two keys k1 and k2 are considered equal if and only if k1==k2 evaluates to true. An entry will automatically be removed when its key is no longer in ordinary use. More precisely, the presence of a mapping for a given key will not prevent the key from being discarded by the garbage collector, that is, made finalizable, finalised, and then reclaimed. When a key has been discarded its entry is effectively removed from the map, so this class behaves somewhat differently from other Map implementations and is not a general-purpose Map implementation! Although it implements the Map interface, it intentionally violates Map's general contract, which mandates the use of the equals method when comparing objects.

This class has performance characteristics similar to those of the HashMap class, and has the same efficiency parameters of initialCapacity and loadFactor. All of the optional map operations are provided. It does not support null values and the null key. All methods taking a key or value will throw a NullPointerException when given a null reference. No guarantees are made as to the order of the map; in particular, there is no guarantee that the order will remain constant over time. Like most collection classes, this class is not synchronised. A synchronised WeakIdentityHashMap may be constructed using the Collections.synchronizedMap method.

The behaviour of the WeakIdentityHashMap class depends in part upon the actions of the garbage collector, so several Map invariants do not hold for this class. Because the garbage collector may discard keys at any time, a WeakIdentityHashMap may behave as though an unknown thread is silently removing entries. In particular, even if synchronising on a WeakIdentityHashMap instance and invoking none of its mutator methods, it is possible for the size method to return smaller values over time, for the isEmpty method to return false and then true, for the containsKey method to return true and later false for a given key, for the get method to return a value for a given key but later return null, for the put method to return null and the remove method to return false for a key that previously appeared to be in the map, and for successive examinations of the key set, the value collection, and the entry set to yield successively smaller numbers of elements. To protect against such situations all Iterators and Entrys created by this class throw an IllegalStateException when a key becomes null or a mapping got removed.

The iterators returned by the iterator method of the collections returned by all of this classes "collection view methods" are fail-fast: if the map is structurally modified at any time after the iterator is created, in any way except through the iterator's own remove method, the iterator will throw a ConcurrentModificationException. Note that the fail-fast behaviour of an iterator cannot be guaranteed as it is, generally speaking, impossible to make any hard guarantees in the presence of unsynchronised concurrent modification. Fail-fast iterators throw ConcurrentModificationExceptions on a best-effort basis. Therefore, it would be wrong to write a program that depends on this exception for its correctness: the fail-fast behaviour of iterators should be used only to detect bugs.

Version:
$JOMC: WeakIdentityHashMap.java 4173 2012-01-15 07:50:51Z schulte2005 $
Author:
Christian Schulte
See Also:
HashMap, WeakHashMap, IdentityHashMap, Collections.synchronizedMap(java.util.Map)

Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
 
Constructor Summary
WeakIdentityHashMap()
          Constructs a new, empty WeakIdentityHashMap with the default initial capacity (16) and load factor (0.75).
WeakIdentityHashMap(float loadFactor)
          Constructs a new, empty WeakIdentityHashMap with the default initial capacity (16) and the given load factor.
WeakIdentityHashMap(int initialCapacity)
          Constructs a new, empty WeakIdentityHashMap with the given initial capacity and the default load factor (0.75).
WeakIdentityHashMap(int initialCapacity, float loadFactor)
          Constructs a new, empty WeakIdentityHashMap with the given initial capacity and the given load factor.
 
Method Summary
 void clear()
          Removes all of the mappings from this map so that the map will be empty after this call returns.
 boolean containsKey(Object key)
          Gets a flag indicating if this map contains a mapping for a given key.
 boolean containsValue(Object value)
          Gets a flag indicating if this map maps one or more keys to the specified value.
 Set<Map.Entry<K,V>> entrySet()
          Gets a Set view of the mappings contained in this map.
 boolean equals(Object o)
          Compares the specified object with this map for equality.
protected  void finalize()
          Finalizes the object by polling the internal reference queue for any pending references.
 V get(Object key)
          Gets the value to which a given key is mapped or null, if this map contains no mapping for that key.
 int hashCode()
          Gets the hash code value for this map.
 boolean isEmpty()
          Gets a flag indicating if this map is empty.
 Set<K> keySet()
          Gets a Set view of the keys contained in this map.
 V put(K key, V value)
          Associates a given value with a given key in this map.
 void putAll(Map<? extends K,? extends V> m)
          Copies all of the mappings from a given map to this map.
 V remove(Object key)
          Removes the mapping for a given key from this map if it is present.
 int size()
          Gets the number of key-value mappings in this map.
 String toString()
          Returns a string representation of the object.
 Collection<V> values()
          Gets a Collection view of the values contained in this map.
 
Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

WeakIdentityHashMap

public WeakIdentityHashMap()
Constructs a new, empty WeakIdentityHashMap with the default initial capacity (16) and load factor (0.75).


WeakIdentityHashMap

public WeakIdentityHashMap(int initialCapacity)
Constructs a new, empty WeakIdentityHashMap with the given initial capacity and the default load factor (0.75).

Parameters:
initialCapacity - The initial capacity of the WeakIdentityHashMap.
Throws:
IllegalArgumentException - if initialCapacity is negative or greater than the maximum supported capacity (2^30).

WeakIdentityHashMap

public WeakIdentityHashMap(float loadFactor)
Constructs a new, empty WeakIdentityHashMap with the default initial capacity (16) and the given load factor.

Parameters:
loadFactor - The load factor of the WeakIdentityHashMap.
Throws:
IllegalArgumentException - if loadFactor is nonpositive.

WeakIdentityHashMap

public WeakIdentityHashMap(int initialCapacity,
                           float loadFactor)
Constructs a new, empty WeakIdentityHashMap with the given initial capacity and the given load factor.

Parameters:
initialCapacity - The initial capacity of the WeakIdentityHashMap.
loadFactor - The load factor of the WeakIdentityHashMap.
Throws:
IllegalArgumentException - if initialCapacity is negative or greater than the maximum supported capacity (2^30), or if loadFactor is nonpositive.
Method Detail

size

public int size()
Gets the number of key-value mappings in this map.

If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:
size in interface Map<K,V>
Returns:
The number of key-value mappings in this map.

isEmpty

public boolean isEmpty()
Gets a flag indicating if this map is empty.

Specified by:
isEmpty in interface Map<K,V>
Returns:
true, if this map contains no key-value mappings; false, if this map contains at least one mapping.

containsKey

public boolean containsKey(Object key)
Gets a flag indicating if this map contains a mapping for a given key.

More formally, returns true, if and only if this map contains a mapping for a key k such that key==k. There can be at most one such mapping.

Specified by:
containsKey in interface Map<K,V>
Parameters:
key - The key whose presence in this map is to be tested.
Returns:
true, if this map contains a mapping for key; false, if this map does not contain a mapping for key.
Throws:
NullPointerException - if key is null.

containsValue

public boolean containsValue(Object value)
Gets a flag indicating if this map maps one or more keys to the specified value.

More formally, this method returns true, if and only if this map contains at least one mapping to a value v such that value.equals(v). This operation requires time linear in the map size.

Specified by:
containsValue in interface Map<K,V>
Parameters:
value - The value whose presence in this map is to be tested.
Returns:
true, if this map maps one or more keys to value; false, if this map does not map any key to value.
Throws:
NullPointerException - if value is null.

get

public V get(Object key)
Gets the value to which a given key is mapped or null, if this map contains no mapping for that key.

More formally, if this map contains a mapping from a key k to a value v such that key==k, then this method returns v; otherwise it returns null. There can be at most one such mapping.

Specified by:
get in interface Map<K,V>
Parameters:
key - The key whose associated value is to be returned.
Returns:
The value to which key is mapped or null, if this map contains no mapping for key.
Throws:
NullPointerException - if key is null.

put

public V put(K key,
             V value)
Associates a given value with a given key in this map.

If the map previously contained a mapping for that key, the old value is replaced by the given value.

Specified by:
put in interface Map<K,V>
Parameters:
key - The key with which value is to be associated.
value - The value to be associated with key.
Returns:
The value previously associated with key or null, if there was no mapping for key.
Throws:
NullPointerException - if key or value is null.

remove

public V remove(Object key)
Removes the mapping for a given key from this map if it is present.

More formally, if this map contains a mapping from key k to value v such that key==k, that mapping is removed. The map can contain at most one such mapping. The map will not contain a mapping for the given key once the call returns.

Specified by:
remove in interface Map<K,V>
Parameters:
key - The key whose mapping is to be removed from the map.
Returns:
The value previously associated with key or null, if there was no mapping for key.
Throws:
NullPointerException - if key is null.

putAll

public void putAll(Map<? extends K,? extends V> m)
Copies all of the mappings from a given map to this map.

The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the given map. The behavior of this operation is undefined if the given map is modified while the operation is in progress.

Specified by:
putAll in interface Map<K,V>
Parameters:
m - The mappings to be stored in this map.
Throws:
NullPointerException - if map is null, or if map contains null keys or values.

clear

public void clear()
Removes all of the mappings from this map so that the map will be empty after this call returns.

Specified by:
clear in interface Map<K,V>

keySet

public Set<K> keySet()
Gets a Set view of the keys contained in this map.

The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the results of the iteration are undefined, that is, the iterator may throw an IllegalStateException. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:
keySet in interface Map<K,V>
Returns:
A set view of the keys contained in this map.

values

public Collection<V> values()
Gets a Collection view of the values contained in this map.

The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator's own remove operation), the results of the iteration are undefined, that is, the iterator may throw an IllegalStateException. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:
values in interface Map<K,V>
Returns:
A collection view of the values contained in this map.

entrySet

public Set<Map.Entry<K,V>> entrySet()
Gets a Set view of the mappings contained in this map.

The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined, that is, the iterator may throw an IllegalStateException. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:
entrySet in interface Map<K,V>
Returns:
A set view of the mappings contained in this map.

toString

public String toString()
Returns a string representation of the object.

Overrides:
toString in class Object
Returns:
A string representation of the object.

equals

public boolean equals(Object o)
Compares the specified object with this map for equality.

Returns true, if the given object is also a map and the two maps represent the same mappings. More formally, two maps m1 and m2 represent the same mappings if m1.entrySet().equals(m2.entrySet()).

Specified by:
equals in interface Map<K,V>
Overrides:
equals in class Object
Parameters:
o - The object to be compared for equality with this map.
Returns:
true, if o is equal to this map; false, if o is not equal to this map.

hashCode

public int hashCode()
Gets the hash code value for this map.

The hash code of a map is defined to be the sum of the hash codes of each entry in the map's entrySet() view.

Specified by:
hashCode in interface Map<K,V>
Overrides:
hashCode in class Object
Returns:
The hash code value for this map.

finalize

protected void finalize()
                 throws Throwable
Finalizes the object by polling the internal reference queue for any pending references.

Overrides:
finalize in class Object
Throws:
Throwable
Since:
1.2


Copyright © 2005-2012 The JOMC Project. All Rights Reserved.Get JOMC at SourceForge.net. Fast, secure and Free Open Source software downloads
Please note that this documentation is maintained by non-native english speaking authors. As such, you may encounter phrases or wordings which seem imprecise or may even have a totally different meaning to native english speaking readers than what the individual author was trying to express. If you are a native english speaking reader and find any such phrases or wordings we kindly ask you to send an email to the corresponding author and help us improve this documentation in order to avoid misunderstandings. You will find the authors' email addresses at the top of each class. Please accept our apologies for any inconvenience caused.