sample/java.util.WeakHashMap.txt

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