TwelveMonkeys/common/common-lang/src/main/java/com/twelvemonkeys/util/LinkedMap.java

/*
 * Copyright (c) 2008, Harald Kuhr
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name "TwelveMonkeys" nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package com.twelvemonkeys.util;

import java.util.*;
import java.io.Serializable;

/**
 * Generic map and linked list implementation of the {@code Map} interface,
 * with predictable iteration order.
 * <p>
 * Resembles {@code LinkedHashMap} from JDK 1.4+, but is backed by a generic
 * {@code Map}, rather than implementing a particular algoritm.
 * <p>
 * This linked list defines the iteration ordering, which is normally the order
 * in which keys were inserted into the map (<em>insertion-order</em>).
 * Note that insertion order is not affected if a key is <em>re-inserted</em>
 * into the map (a key {@code k} is reinserted into a map {@code m} if
 * {@code m.put(k, v)} is invoked when {@code m.containsKey(k)} would return
 * {@code true} immediately prior to the invocation).
 * <p>
 * A special {@link #LinkedMap(boolean) constructor} is provided to create a
 * linked hash map whose order of iteration is the order in which its entries
 * were last accessed, from least-recently accessed to most-recently
 * (<em>access-order</em>).
 * This kind of map is well-suited to building LRU caches.
 * Invoking the {@code put} or {@code get} method results in an access to the
 * corresponding entry (assuming it exists after the invocation completes).
 * The {@code putAll} method generates one entry access for each mapping in
 * the specified map, in the order that key-value mappings are provided by the
 * specified map's entry set iterator.
 * <em>No other methods generate entry accesses.</em>
 * In particular, operations on collection-views do not affect the order of
 * iteration of the backing map.
 * <p>
 * The {@link #removeEldestEntry(Map.Entry)} method may be overridden to impose
 * a policy for removing stale mappings automatically when new mappings are
 * added to the map.
 *
 * @author inspired by LinkedHashMap from JDK 1.4+, by Josh Bloch
 * @author <a href="mailto:harald.kuhr@gmail.com">Harald Kuhr</a>
 * @version $Id: //depot/branches/personal/haraldk/twelvemonkeys/release-2/twelvemonkeys-core/src/main/java/com/twelvemonkeys/util/LinkedMap.java#1 $
 *
 * @see LinkedHashMap
 * @see LRUMap
 */
public class LinkedMap<K, V> extends AbstractDecoratedMap<K, V> implements Serializable {

    transient LinkedEntry<K, V> head;
    protected final boolean accessOrder;

    /**
     * Creates a {@code LinkedMap} backed by a {@code HashMap}, with default
     * (insertion) order.
     */
    public LinkedMap() {
        this(null, false);
    }

    /**
     * Creates a {@code LinkedMap} backed by a {@code HashMap}, with the
     * given order.
     *
     * @param pAccessOrder if {@code true}, ordering will be "least recently
     * accessed item" to "latest accessed item", otherwise "first inserted item"
     * to "latest inserted item".
     */
    public LinkedMap(boolean pAccessOrder) {
        this(null, pAccessOrder);
    }

    /**
     * Creates a {@code LinkedMap} backed by a {@code HashMap}, with key/value
     * pairs copied from {@code pContents} and default (insertion) order.
     *
     * @param pContents the map whose mappings are to be placed in this map.
     * May be {@code null}.
     */
    public LinkedMap(Map<? extends K, ? extends V> pContents) {
        this(pContents, false);
    }

    /**
     * Creates a {@code LinkedMap} backed by a {@code HashMap}, with key/value
     * pairs copied from {@code pContents} and the given order.
     *
     * @param pContents the map whose mappings are to be placed in this map.
     * May be {@code null}.
     * @param pAccessOrder if {@code true}, ordering will be "least recently
     * accessed item" to "latest accessed item", otherwise "first inserted item"
     * to "latest inserted item".
     */
    public LinkedMap(Map<? extends K, ? extends V> pContents, boolean pAccessOrder) {
        super(pContents);
        accessOrder = pAccessOrder;
    }

    /**
     * Creates a {@code LinkedMap} backed by the given map, with key/value
     * pairs copied from {@code pContents} and default (insertion) order.
     *
     * @param pBacking the backing map of this map. Must be either empty, or
     * the same map as {@code pContents}.
     * @param pContents the map whose mappings are to be placed in this map.
     * May be {@code null}.
     */
    public LinkedMap(Map<K, Entry<K, V>> pBacking, Map<? extends K, ? extends V> pContents) {
        this(pBacking, pContents, false);
    }

    /**
     * Creates a {@code LinkedMap} backed by the given map, with key/value
     * pairs copied from {@code pContents} and the given order.
     *
     * @param pBacking the backing map of this map. Must be either empty, or
     * the same map as {@code pContents}.
     * @param pContents the map whose mappings are to be placed in this map.
     * May be {@code null}.
     * @param pAccessOrder if {@code true}, ordering will be "least recently
     * accessed item" to "latest accessed item", otherwise "first inserted item"
     * to "latest inserted item".
     */
    public LinkedMap(Map<K, Entry<K, V>> pBacking, Map<? extends K, ? extends V> pContents, boolean pAccessOrder) {
        super(pBacking, pContents);
        accessOrder = pAccessOrder;
    }

    protected void init() {
        head = new LinkedEntry<K, V>(null, null, null) {
            void addBefore(LinkedEntry pExisting) {
                throw new Error();
            }
            void remove() {
                throw new Error();
            }
            public void recordAccess(Map pMap) {
                throw new Error();
            }
            public void recordRemoval(Map pMap) {
                throw new Error();
            }
            public void recordRemoval() {
                throw new Error();
            }
            public V getValue() {
                throw new Error();
            }
            public V setValue(V pValue) {
                throw new Error();
            }
            public K getKey() {
                throw new Error();
            }
            public String toString() {
                return "head";
            }
        };
        head.previous = head.next = head;
    }

    public boolean containsValue(Object pValue) {
        // Overridden to take advantage of faster iterator
        if (pValue == null) {
            for (LinkedEntry e = head.next; e != head; e = e.next) {
                if (e.mValue == null) {
                    return true;
                }
            }
        } else {
            for (LinkedEntry e = head.next; e != head; e = e.next) {
                if (pValue.equals(e.mValue)) {
                    return true;
                }
            }
        }
        return false;
    }

    protected Iterator<K> newKeyIterator()   {
        return new KeyIterator();
    }

    protected Iterator<V> newValueIterator()   {
        return new ValueIterator();
    }

    protected Iterator<Entry<K, V>> newEntryIterator()   {
        return new EntryIterator();
    }

    private abstract class LinkedMapIterator<E> implements Iterator<E> {
        LinkedEntry<K, V> mNextEntry = head.next;
        LinkedEntry<K, V> mLastReturned = null;

        /**
         * The modCount value that the iterator believes that the backing
         * List should have.  If this expectation is violated, the iterator
         * has detected concurrent modification.
         */
        int mExpectedModCount = modCount;

        public boolean hasNext() {
            return mNextEntry != head;
        }

        public void remove() {
            if (mLastReturned == null) {
                throw new IllegalStateException();
            }

            if (modCount != mExpectedModCount) {
                throw new ConcurrentModificationException();
            }

            LinkedMap.this.remove(mLastReturned.mKey);
            mLastReturned = null;

            mExpectedModCount = modCount;
        }

        LinkedEntry<K, V> nextEntry() {
            if (modCount != mExpectedModCount) {
                throw new ConcurrentModificationException();
            }

            if (mNextEntry == head) {
                throw new NoSuchElementException();
            }

            LinkedEntry<K, V> e = mLastReturned = mNextEntry;
            mNextEntry = e.next;

            return e;
        }
    }

    private class KeyIterator extends LinkedMap<K, V>.LinkedMapIterator<K> {
        public K next() {
            return nextEntry().mKey;
        }
    }

    private class ValueIterator extends LinkedMap<K, V>.LinkedMapIterator<V> {
        public V next() {
            return nextEntry().mValue;
        }
    }

    private class EntryIterator extends LinkedMap<K, V>.LinkedMapIterator<Entry<K, V>> {
        public Entry<K, V> next() {
            return nextEntry();
        }
    }

    public V get(Object pKey) {
        LinkedEntry<K, V> entry = (LinkedEntry<K, V>) entries.get(pKey);

        if (entry != null) {
            entry.recordAccess(this);
            return entry.mValue;
        }

        return null;
    }

    public V remove(Object pKey) {
        LinkedEntry<K, V> entry = (LinkedEntry<K, V>) entries.remove(pKey);

        if (entry != null) {
            entry.remove();
            modCount++;

            return entry.mValue;
        }
        return null;
    }

    public V put(K pKey, V pValue) {
        LinkedEntry<K, V> entry = (LinkedEntry<K, V>) entries.get(pKey);
        V oldValue;

        if (entry == null) {
            oldValue = null;

            // Remove eldest entry if instructed, else grow capacity if appropriate
            LinkedEntry<K, V> eldest = head.next;
            if (removeEldestEntry(eldest)) {
                removeEntry(eldest);
            }

            entry = createEntry(pKey, pValue);
            entry.addBefore(head);

            entries.put(pKey, entry);
        }
        else {
            oldValue = entry.mValue;

            entry.mValue = pValue;
            entry.recordAccess(this);
        }

        modCount++;

        return oldValue;
    }

    /**
     * Creates a new {@code LinkedEntry}.
     *
     * @param pKey the key
     * @param pValue the value
     * @return a new LinkedEntry
     */
    /*protected*/ LinkedEntry<K, V> createEntry(K pKey, V pValue) {
        return new LinkedEntry<K, V>(pKey, pValue, null);
    }

    /**
     * @todo
     *
     * @return a copy of this map, with the same order and same key/value pairs.
     */
    public Object clone() throws CloneNotSupportedException {
        LinkedMap map;

        map = (LinkedMap) super.clone();

        // TODO: The rest of the work is PROBABLY handled by
        // AbstractDecoratedMap, but need to verify that.

        return map;
    }

    /**
     * Returns {@code true} if this map should remove its eldest entry.
     * This method is invoked by {@code put} and {@code putAll} after
     * inserting a new entry into the map.  It provides the implementer
     * with the opportunity to remove the eldest entry each time a new one
     * is added.  This is useful if the map represents a cache: it allows
     * the map to reduce memory consumption by deleting stale entries.
     *
     * <p>Sample use: this override will allow the map to grow up to 100
     * entries and then delete the eldest entry each time a new entry is
     * added, maintaining a steady state of 100 entries.
     * <pre>
     *     private static final int MAX_ENTRIES = 100;
     *
     *     protected boolean removeEldestEntry(Map.Entry eldest) {
     *        return size() > MAX_ENTRIES;
     *     }
     * </pre>
     *
     * <p>This method typically does not modify the map in any way,
     * instead allowing the map to modify itself as directed by its
     * return value.  It <i>is</i> permitted for this method to modify
     * the map directly, but if it does so, it <i>must</i> return
     * {@code false} (indicating that the map should not attempt any
     * further modification).  The effects of returning {@code true}
     * after modifying the map from within this method are unspecified.
     *
     * <p>This implementation merely returns {@code false} (so that this
     * map acts like a normal map - the eldest element is never removed).
     *
     * @param    pEldest The least recently inserted entry in the map, or if
     *           this is an access-ordered map, the least recently accessed
     *           entry.  This is the entry that will be removed it this
     *           method returns {@code true}.  If the map was empty prior
     *           to the {@code put} or {@code putAll} invocation resulting
     *           in this invocation, this will be the entry that was just
     *           inserted; in other words, if the map contains a single
     *           entry, the eldest entry is also the newest.
     * @return   {@code true} if the eldest entry should be removed
     *           from the map; {@code false} if it should be retained.
     */
    protected boolean removeEldestEntry(Entry<K, V> pEldest) {
        return false;
    }

    /**
     * Linked list implementation of {@code Map.Entry}.
     */
    protected static class LinkedEntry<K, V> extends BasicEntry<K, V> implements Serializable {
        LinkedEntry<K, V> previous;
        LinkedEntry<K, V> next;

        LinkedEntry(K pKey, V pValue, LinkedEntry<K, V> pNext) {
            super(pKey, pValue);

            next = pNext;
        }

        /**
         * Adds this entry before the given entry (which must be an existing
         * entry) in the list.
         *
         * @param pExisting the entry to add before
         */
        void addBefore(LinkedEntry<K, V> pExisting) {
            next = pExisting;
            previous = pExisting.previous;

            previous.next = this;
            next.previous = this;
        }

        /**
         * Removes this entry from the linked list.
         */
        void remove() {
            previous.next = next;
            next.previous = previous;
        }

        /**
         * If the entry is part of an access ordered list, moves the entry to
         * the end of the list.
         *
         * @param pMap the map to record access for
         */
        protected void recordAccess(Map<K, V> pMap) {
            LinkedMap<K, V> linkedMap = (LinkedMap<K, V>) pMap;
            if (linkedMap.accessOrder) {
                linkedMap.modCount++;
                remove();
                addBefore(linkedMap.head);
            }
        }

        /**
         * Removes this entry from the linked list.
         *
         * @param pMap the map to record removal from
         */
        protected void recordRemoval(Map<K, V> pMap) {
            // TODO: Is this REALLY correct?
            remove();
        }
    }
}