src/share/classes/java/util/WeakHashMap.java

Print this page




  77  * <tt>false</tt> for a key that previously appeared to be in the map, and
  78  * for successive examinations of the key set, the value collection, and
  79  * the entry set to yield successively smaller numbers of elements.
  80  *
  81  * <p> Each key object in a <tt>WeakHashMap</tt> is stored indirectly as
  82  * the referent of a weak reference.  Therefore a key will automatically be
  83  * removed only after the weak references to it, both inside and outside of the
  84  * map, have been cleared by the garbage collector.
  85  *
  86  * <p> <strong>Implementation note:</strong> The value objects in a
  87  * <tt>WeakHashMap</tt> are held by ordinary strong references.  Thus care
  88  * should be taken to ensure that value objects do not strongly refer to their
  89  * own keys, either directly or indirectly, since that will prevent the keys
  90  * from being discarded.  Note that a value object may refer indirectly to its
  91  * key via the <tt>WeakHashMap</tt> itself; that is, a value object may
  92  * strongly refer to some other key object whose associated value object, in
  93  * turn, strongly refers to the key of the first value object.  One way
  94  * to deal with this is to wrap values themselves within
  95  * <tt>WeakReferences</tt> before
  96  * inserting, as in: <tt>m.put(key, new WeakReference(value))</tt>,
  97  * and then unwrapping upon each <tt>get</tt>.



  98  *
  99  * <p>The iterators returned by the <tt>iterator</tt> method of the collections
 100  * returned by all of this class's "collection view methods" are
 101  * <i>fail-fast</i>: if the map is structurally modified at any time after the
 102  * iterator is created, in any way except through the iterator's own
 103  * <tt>remove</tt> method, the iterator will throw a {@link
 104  * ConcurrentModificationException}.  Thus, in the face of concurrent
 105  * modification, the iterator fails quickly and cleanly, rather than risking
 106  * arbitrary, non-deterministic behavior at an undetermined time in the future.
 107  *
 108  * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
 109  * as it is, generally speaking, impossible to make any hard guarantees in the
 110  * presence of unsynchronized concurrent modification.  Fail-fast iterators
 111  * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
 112  * Therefore, it would be wrong to write a program that depended on this
 113  * exception for its correctness:  <i>the fail-fast behavior of iterators
 114  * should be used only to detect bugs.</i>
 115  *
 116  * <p>This class is a member of the
 117  * <a href="{@docRoot}/../technotes/guides/collections/index.html">




  77  * <tt>false</tt> for a key that previously appeared to be in the map, and
  78  * for successive examinations of the key set, the value collection, and
  79  * the entry set to yield successively smaller numbers of elements.
  80  *
  81  * <p> Each key object in a <tt>WeakHashMap</tt> is stored indirectly as
  82  * the referent of a weak reference.  Therefore a key will automatically be
  83  * removed only after the weak references to it, both inside and outside of the
  84  * map, have been cleared by the garbage collector.
  85  *
  86  * <p> <strong>Implementation note:</strong> The value objects in a
  87  * <tt>WeakHashMap</tt> are held by ordinary strong references.  Thus care
  88  * should be taken to ensure that value objects do not strongly refer to their
  89  * own keys, either directly or indirectly, since that will prevent the keys
  90  * from being discarded.  Note that a value object may refer indirectly to its
  91  * key via the <tt>WeakHashMap</tt> itself; that is, a value object may
  92  * strongly refer to some other key object whose associated value object, in
  93  * turn, strongly refers to the key of the first value object.  One way
  94  * to deal with this is to wrap values themselves within
  95  * <tt>WeakReferences</tt> before
  96  * inserting, as in: <tt>m.put(key, new WeakReference(value))</tt>,
  97  * and then unwrapping upon each <tt>get</tt>. However, as the use of
  98  * <tt>WeakReference</tt> in this manner will not prevent value objects
  99  * from being GC'd, this approach is only useful when entries in the map
 100  * are not relied upon for keeping the underlying value objects "live".
 101  *
 102  * <p>The iterators returned by the <tt>iterator</tt> method of the collections
 103  * returned by all of this class's "collection view methods" are
 104  * <i>fail-fast</i>: if the map is structurally modified at any time after the
 105  * iterator is created, in any way except through the iterator's own
 106  * <tt>remove</tt> method, the iterator will throw a {@link
 107  * ConcurrentModificationException}.  Thus, in the face of concurrent
 108  * modification, the iterator fails quickly and cleanly, rather than risking
 109  * arbitrary, non-deterministic behavior at an undetermined time in the future.
 110  *
 111  * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
 112  * as it is, generally speaking, impossible to make any hard guarantees in the
 113  * presence of unsynchronized concurrent modification.  Fail-fast iterators
 114  * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
 115  * Therefore, it would be wrong to write a program that depended on this
 116  * exception for its correctness:  <i>the fail-fast behavior of iterators
 117  * should be used only to detect bugs.</i>
 118  *
 119  * <p>This class is a member of the
 120  * <a href="{@docRoot}/../technotes/guides/collections/index.html">