- *
- * It uses a hash-bucket approach; that is, hash collisions are handled
- * by linking the new node off of the pre-existing node (or list of
- * nodes). In this manner, techniques such as linear probing (which
- * can cause primary clustering) and rehashing (which does not fit very
- * well with Java's method of precomputing hash codes) are avoided. In
- * addition, this maintains a doubly-linked list which tracks either
- * insertion or access order. Note that the insertion order is not
- * modified if a put simply reinserts a key in the map.
- *
- *
- * One of the nice features of tracking insertion order is that you can
- * copy a hashtable, and regardless of the implementation of the original,
- * produce the same results when iterating over the copy. This is possible
- * without needing the overhead of TreeMap.
- *
- *
- * When using this {@link #LinkedHashMap(int, float, boolean) constructor},
- * you build an access-order mapping. This can be used to implement LRU
- * caches, for example. In this case, every invocation of put,
- * putAll, or get moves the accessed entry to
- * the end of the iteration list. By overriding
- * {@link #removeEldestEntry(Map.Entry)}, you can also control the
- * removal of the oldest entry, and thereby do things like keep the map
- * at a fixed size.
- *
- * - * Under ideal circumstances (no collisions), LinkedHashMap offers O(1) - * performance on most operations (
containsValue()is, - * of course, O(n)). In the worst case (all keys map to the same - * hash code -- very unlikely), most operations are O(n). - *
- *
- * LinkedHashMap accepts the null key and null values. It is not
- * synchronized, so if you need multi-threaded access, consider using:
- * Map m = Collections.synchronizedMap(new LinkedHashMap(...));
- *
- *
- * The iterators are fail-fast, meaning that any structural
- * modification, except for
- *
- * Every element in Map m will be put into this new HashMap, in the
- * order of m's iterator.
- *
- * @param m a Map whose key / value pairs will be put into
- * the new HashMap. NOTE: key / value pairs
- * are not cloned in this constructor.
- * @throws NullPointerException if m is null
- */
- public LinkedHashMap(Map m)
- {
- super(m);
- accessOrder = false;
- }
-
- /**
- * Construct a new insertion-ordered LinkedHashMap with a specific
- * inital capacity and default load factor of 0.75.
- *
- * @param initialCapacity the initial capacity of this HashMap (>= 0)
- * @throws IllegalArgumentException if (initialCapacity < 0)
- */
- public LinkedHashMap(int initialCapacity)
- {
- super(initialCapacity);
- accessOrder = false;
- }
-
- /**
- * Construct a new insertion-orderd LinkedHashMap with a specific
- * inital capacity and load factor.
- *
- * @param initialCapacity the initial capacity (>= 0)
- * @param loadFactor the load factor (> 0, not NaN)
- * @throws IllegalArgumentException if (initialCapacity < 0) ||
- * ! (loadFactor > 0.0)
- */
- public LinkedHashMap(int initialCapacity, float loadFactor)
- {
- super(initialCapacity, loadFactor);
- accessOrder = false;
- }
-
- /**
- * Construct a new LinkedHashMap with a specific inital capacity, load
- * factor, and ordering mode.
- *
- * @param initialCapacity the initial capacity (>=0)
- * @param loadFactor the load factor (>0, not NaN)
- * @param accessOrder true for access-order, false for insertion-order
- * @throws IllegalArgumentException if (initialCapacity < 0) ||
- * ! (loadFactor > 0.0)
- */
- public LinkedHashMap(int initialCapacity, float loadFactor,
- boolean accessOrder)
- {
- super(initialCapacity, loadFactor);
- this.accessOrder = accessOrder;
- }
-
- /**
- * Clears the Map so it has no keys. This is O(1).
- */
- public void clear()
- {
- super.clear();
- head = null;
- tail = null;
- }
-
- /**
- * Returns true if this HashMap contains a value
- *
- * For example, to keep the Map limited to 100 entries, override as follows:
- *
- *
- * Typically, this method does not modify the map, but just uses the
- * return value as an indication to
- *
- * This method is called after the eldest entry has been inserted, so
- * if remove() called on the iterator
- * itself, cause the iterator to throw a
- * {@link ConcurrentModificationException} rather than exhibit
- * non-deterministic behavior.
- *
- * @author Eric Blake true for
- * access-order, false for insertion-order.
- * @serial
- */
- final boolean accessOrder;
-
- /**
- * Class to represent an entry in the hash table. Holds a single key-value
- * pair and the doubly-linked insertion order list.
- */
- class LinkedHashEntry extends HashEntry
- {
- /** The predecessor in the iteration list, null if this is the eldest. */
- LinkedHashEntry pred;
- /** The successor in the iteration list, null if this is the newest. */
- LinkedHashEntry succ;
-
- /**
- * Simple constructor.
- * @param key the key
- * @param value the value
- */
- LinkedHashEntry(Object key, Object value)
- {
- super(key, value);
- if (head == null)
- head = this;
- pred = tail;
- tail = this;
- if (pred != null)
- pred.succ = this;
- }
-
- /**
- * Sets the value of this entry, and shuffles it to the end of
- * the list if this is in access-order.
- * @param value the new value
- * @return the prior value
- */
- public Object setValue(Object value)
- {
- if (accessOrder && succ != null)
- {
- succ.pred = pred;
- if (pred == null)
- head = succ;
- else
- pred.succ = succ;
- succ = null;
- pred = tail;
- pred.succ = this;
- tail = this;
- }
- return super.setValue(value);
- }
-
- /**
- * Called when this entry is removed from the map. This version does
- * the necessary bookkeeping to keep the doubly-linked list in order.
- * @return the value of this key as it is removed
- */
- Object cleanup()
- {
- if (pred == null)
- head = succ;
- else
- pred.succ = succ;
- if (succ == null)
- tail = pred;
- else
- succ.pred = pred;
-
- return value;
- }
- }
-
- /**
- * Construct a new insertion-ordered LinkedHashMap with the default
- * capacity (11) and the default load factor (0.75).
- */
- public LinkedHashMap()
- {
- super();
- accessOrder = false;
- }
-
- /**
- * Construct a new insertion-ordered LinkedHashMap from the given Map,
- * with initial capacity the greater of the size of m or
- * the default of 11.
- * o
, such that
- * o.equals(value)
.
- *
- * @param value the value to search for in this HashMap
- * @return true if at least one key maps to the value
- */
- public boolean containsValue(Object value)
- {
- LinkedHashEntry e = head;
- while (e != null)
- {
- if (equals(value, e.value))
- return true;
- e = e.succ;
- }
- return false;
- }
-
- /**
- * Return the value in this Map associated with the supplied key,
- * or null
if the key maps to nothing. If this is an
- * access-ordered Map and the key is found, this performs structural
- * modification, moving the key to the newest end of the list. NOTE:
- * Since the value could also be null, you must use containsKey to
- * see if this key actually maps to something.
- *
- * @param key the key for which to fetch an associated value
- * @return what the key maps to, if present
- * @see #put(Object, Object)
- * @see #containsKey(Object)
- */
- public Object get(Object key)
- {
- int idx = hash(key);
- HashEntry e = buckets[idx];
- while (e != null)
- {
- if (equals(key, e.key))
- {
- if (accessOrder)
- {
- modCount++;
- LinkedHashEntry l = (LinkedHashEntry) e;
- if (l.succ != null)
- {
- l.succ.pred = l.pred;
- if (l.pred == null)
- head = l.succ;
- else
- l.pred.succ = l.succ;
- l.succ = null;
- l.pred = tail;
- tail.succ = l;
- tail = l;
- }
- }
- return e.value;
- }
- e = e.next;
- }
- return null;
- }
-
- /**
- * Returns true if this map should remove the eldest entry.
- * This method is invoked by all calls to put and
- * putAll which place a new entry in the map, providing
- * the implementer an opportunity to remove the eldest entry any time
- * a new one is added. This can be used to save memory usage of the
- * hashtable, as well as emulating a cache, by deleting stale entries.
- *
- * private static final int MAX_ENTRIES = 100;
- *
- * protected boolean removeEldestEntry(Map.Entry eldest)
- * {
- * return size() > MAX_ENTRIES;
- * }
- * put whether to proceed.
- * However, if you override it to modify the map, you must return false
- * (indicating that put should do nothing), or face
- * unspecified behavior.
- * put was called on a previously empty map, the eldest
- * entry is the one you just put in! The default implementation just
- * returns false, so that this map always behaves like
- * a normal one with unbounded growth.
- *
- * @param eldest the eldest element which would be removed if this
- * returns true. For an access-order map, this is the least
- * recently accessed; for an insertion-order map, this is the
- * earliest element inserted.
- * @return true if eldest should be removed
- */
- protected boolean removeEldestEntry(Map.Entry eldest)
- {
- return false;
- }
-
- /**
- * Helper method called by put, which creates and adds a
- * new Entry, followed by performing bookkeeping (like removeEldestEntry).
- *
- * @param key the key of the new Entry
- * @param value the value
- * @param idx the index in buckets where the new Entry belongs
- * @param callRemove whether to call the removeEldestEntry method
- * @see #put(Object, Object)
- * @see #removeEldestEntry(Map.Entry)
- */
- void addEntry(Object key, Object value, int idx, boolean callRemove)
- {
- LinkedHashEntry e = new LinkedHashEntry(key, value);
-
- e.next = buckets[idx];
- buckets[idx] = e;
-
- if (callRemove && removeEldestEntry(head))
- remove(head);
- }
-
- /**
- * Helper method, called by clone() to reset the doubly-linked list.
- * @param m the map to add entries from
- * @see #clone()
- */
- void putAllInternal(Map m)
- {
- head = null;
- tail = null;
- super.putAllInternal(m);
- }
-
- /**
- * Generates a parameterized iterator. This allows traversal to follow
- * the doubly-linked list instead of the random bin order of HashMap.
- * @param type {@link #KEYS}, {@link #VALUES}, or {@link #ENTRIES}
- * @return the appropriate iterator
- */
- Iterator iterator(final int type)
- {
- return new Iterator()
- {
- /** The current Entry */
- LinkedHashEntry current = head;
-
- /** The previous Entry returned by next() */
- LinkedHashEntry last;
-
- /** The number of known modifications to the backing HashMap */
- int knownMod = modCount;
-
- /**
- * Returns true if the Iterator has more elements.
- * @return true if there are more elements
- * @throws ConcurrentModificationException if the HashMap was modified
- */
- public boolean hasNext()
- {
- if (knownMod != modCount)
- throw new ConcurrentModificationException();
- return current != null;
- }
-
- /**
- * Returns the next element in the Iterator's sequential view.
- * @return the next element
- * @throws ConcurrentModificationException if the HashMap was modified
- * @throws NoSuchElementException if there is none
- */
- public Object next()
- {
- if (knownMod != modCount)
- throw new ConcurrentModificationException();
- if (current == null)
- throw new NoSuchElementException();
- last = current;
- current = current.succ;
- return type == VALUES ? last.value : type == KEYS ? last.key : last;
- }
-
- /**
- * Removes from the backing HashMap the last element which was fetched
- * with the next()
method.
- * @throws ConcurrentModificationException if the HashMap was modified
- * @throws IllegalStateException if called when there is no last element
- */
- public void remove()
- {
- if (knownMod != modCount)
- throw new ConcurrentModificationException();
- if (last == null)
- throw new IllegalStateException();
-
- LinkedHashMap.this.remove(last.key);
- last = null;
- knownMod++;
- }
- };
- }
-}