sample/java.util.LinkedHashMap.txt

   1 *java.util.LinkedHashMap* *LinkedHashMap* Hash table and linked list implementat
   2
   3 public class LinkedHashMap<K,V>
   4   extends    |java.util.HashMap|
   5   implements |java.util.Map|
   6
   7 |java.util.LinkedHashMap_Description|
   8 |java.util.LinkedHashMap_Fields|
   9 |java.util.LinkedHashMap_Constructors|
  10 |java.util.LinkedHashMap_Methods|
  11
  12 ================================================================================
  13
  14 *java.util.LinkedHashMap_Constructors*
  15 |java.util.LinkedHashMap()|Constructs an empty insertion-ordered LinkedHashMap
  16 |java.util.LinkedHashMap(int)|Constructs an empty insertion-ordered LinkedHashM
  17 |java.util.LinkedHashMap(int,float)|Constructs an empty insertion-ordered Linke
  18 |java.util.LinkedHashMap(int,float,boolean)|Constructs an empty LinkedHashMap i
  19 |java.util.LinkedHashMap(Map<?extendsK,?extendsV>)|Constructs an insertion-orde
  20
  21 *java.util.LinkedHashMap_Methods*
  22 |java.util.LinkedHashMap.clear()|Removes all of the mappings from this map.
  23 |java.util.LinkedHashMap.containsValue(Object)|Returns true if this map maps on
  24 |java.util.LinkedHashMap.get(Object)|Returns the value to which the specified k
  25 |java.util.LinkedHashMap.removeEldestEntry(Map.Entry<K,V>)|Returns true if this
  26
  27 *java.util.LinkedHashMap_Description*
  28
  29 Hash table and linked list implementation of the Map interface, with
  30 predictable iteration order. This implementation differs from HashMap in that
  31 it maintains a doubly-linked list running through all of its entries. This
  32 linked list defines the iteration ordering, which is normally the order in
  33 which keys were inserted into the map (insertion-order). Note that insertion
  34 order is not affected if a key is re-inserted into the map. (A key k is
  35 reinserted into a map m if m.put(k, v) is invoked when m.containsKey(k) would
  36 return true immediately prior to the invocation.)
  37
  38 This implementation spares its clients from the unspecified, generally chaotic
  39 ordering provided by (|java.util.HashMap|) (and (|java.util.Hashtable|) ),
  40 without incurring the increased cost associated with (|java.util.TreeMap|) . It
  41 can be used to produce a copy of a map that has the same order as the original,
  42 regardless of the original map's implementation:
  43
  44 void foo(Map m) { Map copy = new LinkedHashMap(m); ... }
  45
  46 This technique is particularly useful if a module takes a map on input, copies
  47 it, and later returns results whose order is determined by that of the copy.
  48 (Clients generally appreciate having things returned in the same order they
  49 were presented.)
  50
  51 A special constructor(|java.util.LinkedHashMap|) is provided to create a linked
  52 hash map whose order of iteration is the order in which its entries were last
  53 accessed, from least-recently accessed to most-recently (access-order). This
  54 kind of map is well-suited to building LRU caches. Invoking the put or get
  55 method results in an access to the corresponding entry (assuming it exists
  56 after the invocation completes). The putAll method generates one entry access
  57 for each mapping in the specified map, in the order that key-value mappings are
  58 provided by the specified map's entry set iterator. No other methods generate
  59 entry accesses. In particular, operations on collection-views do not affect the
  60 order of iteration of the backing map.
  61
  62 The (|java.util.LinkedHashMap|) method may be overridden to impose a policy for
  63 removing stale mappings automatically when new mappings are added to the map.
  64
  65 This class provides all of the optional Map operations, and permits null
  66 elements. Like HashMap, it provides constant-time performance for the basic
  67 operations (add, contains and remove), assuming the hash function disperses
  68 elements properly among the buckets. Performance is likely to be just slightly
  69 below that of HashMap, due to the added expense of maintaining the linked list,
  70 with one exception: Iteration over the collection-views of a LinkedHashMap
  71 requires time proportional to the size of the map, regardless of its capacity.
  72 Iteration over a HashMap is likely to be more expensive, requiring time
  73 proportional to its capacity.
  74
  75 A linked hash map has two parameters that affect its performance: initial
  76 capacity and load factor. They are defined precisely as for HashMap. Note,
  77 however, that the penalty for choosing an excessively high value for initial
  78 capacity is less severe for this class than for HashMap, as iteration times for
  79 this class are unaffected by capacity.
  80
  81 Note that this implementation is not synchronized. If multiple threads access a
  82 linked hash map concurrently, and at least one of the threads modifies the map
  83 structurally, it must be synchronized externally. This is typically
  84 accomplished by synchronizing on some object that naturally encapsulates the
  85 map.
  86
  87 If no such object exists, the map should be "wrapped" using the
  88 Collections.synchronizedMap(|java.util.Collections|) method. This is best done
  89 at creation time, to prevent accidental unsynchronized access to the map:
  90
  91 Map m = Collections.synchronizedMap(new LinkedHashMap(...));
  92
  93 A structural modification is any operation that adds or deletes one or more
  94 mappings or, in the case of access-ordered linked hash maps, affects iteration
  95 order. In insertion-ordered linked hash maps, merely changing the value
  96 associated with a key that is already contained in the map is not a structural
  97 modification. In access-ordered linked hash maps, merely querying the map with
  98 get is a structural modification.)
  99
 100 The iterators returned by the iterator method of the collections returned by
 101 all of this class's collection view methods are fail-fast: if the map is
 102 structurally modified at any time after the iterator is created, in any way
 103 except through the iterator's own remove method, the iterator will throw a
 104 (|java.util.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 Note that the fail-fast behavior of an iterator cannot be guaranteed as it is,
 109 generally speaking, impossible to make any hard guarantees in the presence of
 110 unsynchronized concurrent modification. Fail-fast iterators throw
 111 ConcurrentModificationException on a best-effort basis. Therefore, it would be
 112 wrong to write a program that depended on this exception for its correctness:
 113 the fail-fast behavior of iterators should be used only to detect bugs.
 114
 115 This class is a member of the <a
 116 href="/../technotes/guides/collections/index.html"> Java Collections Framework.
 117
 118
 119
 120 *java.util.LinkedHashMap()*
 121
 122 public LinkedHashMap()
 123
 124 Constructs an empty insertion-ordered LinkedHashMap instance with the default
 125 initial capacity (16) and load factor (0.75).
 126
 127
 128 *java.util.LinkedHashMap(int)*
 129
 130 public LinkedHashMap(int initialCapacity)
 131
 132 Constructs an empty insertion-ordered LinkedHashMap instance with the specified
 133 initial capacity and a default load factor (0.75).
 134
 135     initialCapacity - the initial capacity
 136
 137 *java.util.LinkedHashMap(int,float)*
 138
 139 public LinkedHashMap(
 140   int initialCapacity,
 141   float loadFactor)
 142
 143 Constructs an empty insertion-ordered LinkedHashMap instance with the specified
 144 initial capacity and load factor.
 145
 146     initialCapacity - the initial capacity
 147     loadFactor - the load factor
 148
 149 *java.util.LinkedHashMap(int,float,boolean)*
 150
 151 public LinkedHashMap(
 152   int initialCapacity,
 153   float loadFactor,
 154   boolean accessOrder)
 155
 156 Constructs an empty LinkedHashMap instance with the specified initial capacity,
 157 load factor and ordering mode.
 158
 159     initialCapacity - the initial capacity
 160     loadFactor - the load factor
 161     accessOrder - the ordering mode - true for access-order, false for insertion-order
 162
 163 *java.util.LinkedHashMap(Map<?extendsK,?extendsV>)*
 164
 165 public LinkedHashMap(java.util.Map<? extends K, ? extends V> m)
 166
 167 Constructs an insertion-ordered LinkedHashMap instance with the same mappings
 168 as the specified map. The LinkedHashMap instance is created with a default load
 169 factor (0.75) and an initial capacity sufficient to hold the mappings in the
 170 specified map.
 171
 172     m - the map whose mappings are to be placed in this map
 173
 174 *java.util.LinkedHashMap.clear()*
 175
 176 public void clear()
 177
 178 Removes all of the mappings from this map. The map will be empty after this
 179 call returns.
 180
 181
 182
 183 *java.util.LinkedHashMap.containsValue(Object)*
 184
 185 public boolean containsValue(java.lang.Object value)
 186
 187 Returns true if this map maps one or more keys to the specified value.
 188
 189
 190     value - value whose presence in this map is to be tested
 191
 192     Returns: true if this map maps one or more keys to the specified value
 193
 194 *java.util.LinkedHashMap.get(Object)*
 195
 196 public |V| get(java.lang.Object key)
 197
 198 Returns the value to which the specified key is mapped, ornullif this map
 199 contains no mapping for the key.
 200
 201 More formally, if this map contains a mapping from a keykto a valuevsuch
 202 that(key==null ? k==null : key.equals(k)), then this method returnsv; otherwise
 203 it returnsnull. (There can be at most one such mapping.)
 204
 205 A return value ofnulldoes not necessarily indicate that the map contains no
 206 mapping for the key; it's also possible that the map explicitly maps the key
 207 tonull. The containsKey(|java.util.LinkedHashMap|) operation may be used to
 208 distinguish these two cases.
 209
 210
 211
 212 *java.util.LinkedHashMap.removeEldestEntry(Map.Entry<K,V>)*
 213
 214 protected boolean removeEldestEntry(java.util.Map.Entry<K, V> eldest)
 215
 216 Returns true if this map should remove its eldest entry. This method is invoked
 217 by put and putAll after inserting a new entry into the map. It provides the
 218 implementor with the opportunity to remove the eldest entry each time a new one
 219 is added. This is useful if the map represents a cache: it allows the map to
 220 reduce memory consumption by deleting stale entries.
 221
 222 Sample use: this override will allow the map to grow up to 100 entries and then
 223 delete the eldest entry each time a new entry is added, maintaining a steady
 224 state of 100 entries.
 225
 226 private static final int MAX_ENTRIES = 100;
 227
 228 protected boolean removeEldestEntry(Map.Entry eldest) { return size() >
 229 MAX_ENTRIES; }
 230
 231 This method typically does not modify the map in any way, instead allowing the
 232 map to modify itself as directed by its return value. It is permitted for this
 233 method to modify the map directly, but if it does so, it must return false
 234 (indicating that the map should not attempt any further modification). The
 235 effects of returning true after modifying the map from within this method are
 236 unspecified.
 237
 238 This implementation merely returns false (so that this map acts like a normal
 239 map - the eldest element is never removed).
 240
 241
 242     eldest - The least recently inserted entry in the map, or if this is an access-ordered
 243        map, the least recently accessed entry. This is the entry that will be
 244        removed it this method returns true. If the map was empty prior to the
 245        put or putAll invocation resulting in this invocation, this will be the
 246        entry that was just inserted; in other words, if the map contains a
 247        single entry, the eldest entry is also the newest.
 248
 249     Returns: true if the eldest entry should be removed from the map; false if it should be
 250              retained.
 251
 252