73  * <tt>true</tt> and later <tt>false</tt> for a given key, for the
  74  * <tt>get</tt> method to return a value for a given key but later return
  75  * <tt>null</tt>, for the <tt>put</tt> method to return
  76  * <tt>null</tt> and the <tt>remove</tt> method to return
  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

  73  * <tt>true</tt> and later <tt>false</tt> for a given key, for the
  74  * <tt>get</tt> method to return a value for a given key but later return
  75  * <tt>null</tt>, for the <tt>put</tt> method to return
  76  * <tt>null</tt> and the <tt>remove</tt> method to return
  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.  If the values
  94  * in the map do not rely on the map holding strong references to them, one way
  95  * to deal with this is to wrap values themselves within
  96  * <tt>WeakReferences</tt> before
  97  * inserting, as in: <tt>m.put(key, new WeakReference(value))</tt>,
  98  * and then unwrapping upon each <tt>get</tt>.
  99  *
 100  * <p>The iterators returned by the <tt>iterator</tt> method of the collections
 101  * returned by all of this class's "collection view methods" are
 102  * <i>fail-fast</i>: if the map is structurally modified at any time after the
 103  * iterator is created, in any way except through the iterator's own
 104  * <tt>remove</tt> method, the iterator will throw a {@link
 105  * ConcurrentModificationException}.  Thus, in the face of concurrent
 106  * modification, the iterator fails quickly and cleanly, rather than risking
 107  * arbitrary, non-deterministic behavior at an undetermined time in the future.
 108  *
 109  * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
 110  * as it is, generally speaking, impossible to make any hard guarantees in the
 111  * presence of unsynchronized concurrent modification.  Fail-fast iterators
 112  * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
 113  * Therefore, it would be wrong to write a program that depended on this
 114  * exception for its correctness:  <i>the fail-fast behavior of iterators