sample/java.util.WeakHashMap.txt

   1 *java.util.WeakHashMap* *WeakHashMap* A hashtable-based Map implementation with
   2
   3 public class WeakHashMap<K,V>
   4   extends    |java.util.AbstractMap|
   5   implements |java.util.Map|
   6
   7 |java.util.WeakHashMap_Description|
   8 |java.util.WeakHashMap_Fields|
   9 |java.util.WeakHashMap_Constructors|
  10 |java.util.WeakHashMap_Methods|
  11
  12 ================================================================================
  13
  14 *java.util.WeakHashMap_Constructors*
  15 |java.util.WeakHashMap()|Constructs a new, empty WeakHashMap with the default i
  16 |java.util.WeakHashMap(int)|Constructs a new, empty WeakHashMap with the given
  17 |java.util.WeakHashMap(int,float)|Constructs a new, empty WeakHashMap with the
  18 |java.util.WeakHashMap(Map<?extendsK,?extendsV>)|Constructs a new WeakHashMap w
  19
  20 *java.util.WeakHashMap_Methods*
  21 |java.util.WeakHashMap.clear()|Removes all of the mappings from this map.
  22 |java.util.WeakHashMap.containsKey(Object)|Returns true if this map contains a
  23 |java.util.WeakHashMap.containsValue(Object)|Returns true if this map maps one
  24 |java.util.WeakHashMap.entrySet()|Returns aSetview of the mappings contained in
  25 |java.util.WeakHashMap.get(Object)|Returns the value to which the specified key
  26 |java.util.WeakHashMap.isEmpty()|Returns true if this map contains no key-value
  27 |java.util.WeakHashMap.keySet()|Returns aSetview of the keys contained in this
  28 |java.util.WeakHashMap.put(K,V)|Associates the specified value with the specifi
  29 |java.util.WeakHashMap.putAll(Map<?extendsK,?extendsV>)|Copies all of the mappi
  30 |java.util.WeakHashMap.remove(Object)|Removes the mapping for a key from this w
  31 |java.util.WeakHashMap.size()|Returns the number of key-value mappings in this
  32 |java.util.WeakHashMap.values()|Returns aCollectionview of the values contained
  33
  34 *java.util.WeakHashMap_Description*
  35
  36 A hashtable-based Map implementation with weak keys. An entry in a WeakHashMap
  37 will automatically be removed when its key is no longer in ordinary use. More
  38 precisely, the presence of a mapping for a given key will not prevent the key
  39 from being discarded by the garbage collector, that is, made finalizable,
  40 finalized, and then reclaimed. When a key has been discarded its entry is
  41 effectively removed from the map, so this class behaves somewhat differently
  42 from other Map implementations.
  43
  44 Both null values and the null key are supported. This class has performance
  45 characteristics similar to those of the HashMap class, and has the same
  46 efficiency parameters of initial capacity and load factor.
  47
  48 Like most collection classes, this class is not synchronized. A synchronized
  49 WeakHashMap may be constructed using the
  50 Collections.synchronizedMap(|java.util.Collections|) method.
  51
  52 This class is intended primarily for use with key objects whose equals methods
  53 test for object identity using the == operator. Once such a key is discarded it
  54 can never be recreated, so it is impossible to do a lookup of that key in a
  55 WeakHashMap at some later time and be surprised that its entry has been
  56 removed. This class will work perfectly well with key objects whose equals
  57 methods are not based upon object identity, such as String instances. With such
  58 recreatable key objects, however, the automatic removal of WeakHashMap entries
  59 whose keys have been discarded may prove to be confusing.
  60
  61 The behavior of the WeakHashMap class depends in part upon the actions of the
  62 garbage collector, so several familiar (though not required) Map invariants do
  63 not hold for this class. Because the garbage collector may discard keys at any
  64 time, a WeakHashMap may behave as though an unknown thread is silently removing
  65 entries. In particular, even if you synchronize on a WeakHashMap instance and
  66 invoke none of its mutator methods, it is possible for the size method to
  67 return smaller values over time, for the isEmpty method to return false and
  68 then true, for the containsKey method to return true and later false for a
  69 given key, for the get method to return a value for a given key but later
  70 return null, for the put method to return null and the remove method to return
  71 false for a key that previously appeared to be in the map, and for successive
  72 examinations of the key set, the value collection, and the entry set to yield
  73 successively smaller numbers of elements.
  74
  75 Each key object in a WeakHashMap is stored indirectly as the referent of a weak
  76 reference. Therefore a key will automatically be removed only after the weak
  77 references to it, both inside and outside of the map, have been cleared by the
  78 garbage collector.
  79
  80 Implementation note: The value objects in a WeakHashMap are held by ordinary
  81 strong references. Thus care should be taken to ensure that value objects do
  82 not strongly refer to their own keys, either directly or indirectly, since that
  83 will prevent the keys from being discarded. Note that a value object may refer
  84 indirectly to its key via the WeakHashMap itself; that is, a value object may
  85 strongly refer to some other key object whose associated value object, in turn,
  86 strongly refers to the key of the first value object. One way to deal with this
  87 is to wrap values themselves within WeakReferences before inserting, as in:
  88 m.put(key, new WeakReference(value)), and then unwrapping upon each get.
  89
  90 The iterators returned by the iterator method of the collections returned by
  91 all of this class's "collection view methods" are fail-fast: if the map is
  92 structurally modified at any time after the iterator is created, in any way
  93 except through the iterator's own remove method, the iterator will throw a
  94 (|java.util.ConcurrentModificationException|) . Thus, in the face of concurrent
  95 modification, the iterator fails quickly and cleanly, rather than risking
  96 arbitrary, non-deterministic behavior at an undetermined time in the future.
  97
  98 Note that the fail-fast behavior of an iterator cannot be guaranteed as it is,
  99 generally speaking, impossible to make any hard guarantees in the presence of
 100 unsynchronized concurrent modification. Fail-fast iterators throw
 101 ConcurrentModificationException on a best-effort basis. Therefore, it would be
 102 wrong to write a program that depended on this exception for its correctness:
 103 the fail-fast behavior of iterators should be used only to detect bugs.
 104
 105 This class is a member of the <a
 106 href="/../technotes/guides/collections/index.html"> Java Collections Framework.
 107
 108
 109
 110 *java.util.WeakHashMap()*
 111
 112 public WeakHashMap()
 113
 114 Constructs a new, empty WeakHashMap with the default initial capacity (16) and
 115 load factor (0.75).
 116
 117
 118 *java.util.WeakHashMap(int)*
 119
 120 public WeakHashMap(int initialCapacity)
 121
 122 Constructs a new, empty WeakHashMap with the given initial capacity and the
 123 default load factor (0.75).
 124
 125     initialCapacity - The initial capacity of the WeakHashMap
 126
 127 *java.util.WeakHashMap(int,float)*
 128
 129 public WeakHashMap(
 130   int initialCapacity,
 131   float loadFactor)
 132
 133 Constructs a new, empty WeakHashMap with the given initial capacity and the
 134 given load factor.
 135
 136     initialCapacity - The initial capacity of the WeakHashMap
 137     loadFactor - The load factor of the WeakHashMap
 138
 139 *java.util.WeakHashMap(Map<?extendsK,?extendsV>)*
 140
 141 public WeakHashMap(java.util.Map<? extends K, ? extends V> m)
 142
 143 Constructs a new WeakHashMap with the same mappings as the specified map. The
 144 WeakHashMap is created with the default load factor (0.75) and an initial
 145 capacity sufficient to hold the mappings in the specified map.
 146
 147     m - the map whose mappings are to be placed in this map
 148
 149 *java.util.WeakHashMap.clear()*
 150
 151 public void clear()
 152
 153 Removes all of the mappings from this map. The map will be empty after this
 154 call returns.
 155
 156
 157
 158 *java.util.WeakHashMap.containsKey(Object)*
 159
 160 public boolean containsKey(java.lang.Object key)
 161
 162 Returns true if this map contains a mapping for the specified key.
 163
 164
 165     key - The key whose presence in this map is to be tested
 166
 167     Returns: true if there is a mapping for key; false otherwise
 168
 169 *java.util.WeakHashMap.containsValue(Object)*
 170
 171 public boolean containsValue(java.lang.Object value)
 172
 173 Returns true if this map maps one or more keys to the specified value.
 174
 175
 176     value - value whose presence in this map is to be tested
 177
 178     Returns: true if this map maps one or more keys to the specified value
 179
 180 *java.util.WeakHashMap.entrySet()*
 181
 182 public |java.util.Set|<Entry<K,V>> entrySet()
 183
 184 Returns a (|java.util.Set|) view of the mappings contained in this map. The set
 185 is backed by the map, so changes to the map are reflected in the set, and
 186 vice-versa. If the map is modified while an iteration over the set is in
 187 progress (except through the iterator's own remove operation, or through the
 188 setValue operation on a map entry returned by the iterator) the results of the
 189 iteration are undefined. The set supports element removal, which removes the
 190 corresponding mapping from the map, via the Iterator.remove, Set.remove,
 191 removeAll, retainAll and clear operations. It does not support the add or
 192 addAll operations.
 193
 194
 195
 196 *java.util.WeakHashMap.get(Object)*
 197
 198 public |V| get(java.lang.Object key)
 199
 200 Returns the value to which the specified key is mapped, ornullif this map
 201 contains no mapping for the key.
 202
 203 More formally, if this map contains a mapping from a keykto a valuevsuch
 204 that(key==null ? k==null : key.equals(k)), then this method returnsv; otherwise
 205 it returnsnull. (There can be at most one such mapping.)
 206
 207 A return value ofnulldoes not necessarily indicate that the map contains no
 208 mapping for the key; it's also possible that the map explicitly maps the key
 209 tonull. The containsKey(|java.util.WeakHashMap|) operation may be used to
 210 distinguish these two cases.
 211
 212
 213
 214 *java.util.WeakHashMap.isEmpty()*
 215
 216 public boolean isEmpty()
 217
 218 Returns true if this map contains no key-value mappings. This result is a
 219 snapshot, and may not reflect unprocessed entries that will be removed before
 220 next attempted access because they are no longer referenced.
 221
 222
 223
 224 *java.util.WeakHashMap.keySet()*
 225
 226 public |java.util.Set|<K> keySet()
 227
 228 Returns a (|java.util.Set|) view of the keys contained in this map. The set is
 229 backed by the map, so changes to the map are reflected in the set, and
 230 vice-versa. If the map is modified while an iteration over the set is in
 231 progress (except through the iterator's own remove operation), the results of
 232 the iteration are undefined. The set supports element removal, which removes
 233 the corresponding mapping from the map, via the Iterator.remove, Set.remove,
 234 removeAll, retainAll, and clear operations. It does not support the add or
 235 addAll operations.
 236
 237
 238
 239 *java.util.WeakHashMap.put(K,V)*
 240
 241 public |V| put(
 242   K key,
 243   V value)
 244
 245 Associates the specified value with the specified key in this map. If the map
 246 previously contained a mapping for this key, the old value is replaced.
 247
 248
 249     key - key with which the specified value is to be associated.
 250     value - value to be associated with the specified key.
 251
 252     Returns: the previous value associated with key, or null if there was no mapping for
 253              key. (A null return can also indicate that the map previously
 254              associated null with key.)
 255
 256 *java.util.WeakHashMap.putAll(Map<?extendsK,?extendsV>)*
 257
 258 public void putAll(java.util.Map<? extends K, ? extends V> m)
 259
 260 Copies all of the mappings from the specified map to this map. These mappings
 261 will replace any mappings that this map had for any of the keys currently in
 262 the specified map.
 263
 264
 265     m - mappings to be stored in this map.
 266
 267 *java.util.WeakHashMap.remove(Object)*
 268
 269 public |V| remove(java.lang.Object key)
 270
 271 Removes the mapping for a key from this weak hash map if it is present. More
 272 formally, if this map contains a mapping from key k to value v such that
 273 (key==null ? k==null : key.equals(k)), that mapping is removed. (The map can
 274 contain at most one such mapping.)
 275
 276 Returns the value to which this map previously associated the key, or null if
 277 the map contained no mapping for the key. A return value of null does not
 278 necessarily indicate that the map contained no mapping for the key; it's also
 279 possible that the map explicitly mapped the key to null.
 280
 281 The map will not contain a mapping for the specified key once the call returns.
 282
 283
 284     key - key whose mapping is to be removed from the map
 285
 286     Returns: the previous value associated with key, or null if there was no mapping for key
 287
 288 *java.util.WeakHashMap.size()*
 289
 290 public int size()
 291
 292 Returns the number of key-value mappings in this map. This result is a
 293 snapshot, and may not reflect unprocessed entries that will be removed before
 294 next attempted access because they are no longer referenced.
 295
 296
 297
 298 *java.util.WeakHashMap.values()*
 299
 300 public |java.util.Collection|<V> values()
 301
 302 Returns a (|java.util.Collection|) view of the values contained in this map.
 303 The collection is backed by the map, so changes to the map are reflected in the
 304 collection, and vice-versa. If the map is modified while an iteration over the
 305 collection is in progress (except through the iterator's own remove operation),
 306 the results of the iteration are undefined. The collection supports element
 307 removal, which removes the corresponding mapping from the map, via the
 308 Iterator.remove, Collection.remove, removeAll, retainAll and clear operations.
 309 It does not support the add or addAll operations.
 310
 311
 312
 313