/*

 * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.util;

import java.lang.ref.WeakReference;

import java.lang.ref.ReferenceQueue;

/**

 * Hash table based implementation of the <tt>Map</tt> interface, with

 * <em>weak keys</em>.

 * An entry in a <tt>WeakHashMap</tt> will automatically be removed when

 * its key is no longer in ordinary use.  More precisely, the presence of a

 * mapping for a given key will not prevent the key from being discarded by the

 * garbage collector, that is, made finalizable, finalized, and then reclaimed.

 * When a key has been discarded its entry is effectively removed from the map,

 * so this class behaves somewhat differently from other <tt>Map</tt>

 * implementations.

 *

 * <p> Both null values and the null key are supported. This class has

 * performance characteristics similar to those of the <tt>HashMap</tt>

 * class, and has the same efficiency parameters of <em>initial capacity</em>

 * and <em>load factor</em>.

 *

 * <p> Like most collection classes, this class is not synchronized.

 * A synchronized <tt>WeakHashMap</tt> may be constructed using the

 * {@link Collections#synchronizedMap Collections.synchronizedMap}

 * method.

 *

 * <p> This class is intended primarily for use with key objects whose

 * <tt>equals</tt> methods test for object identity using the

 * <tt>==</tt> operator.  Once such a key is discarded it can never be

 * recreated, so it is impossible to do a lookup of that key in a

 * <tt>WeakHashMap</tt> at some later time and be surprised that its entry

 * has been removed.  This class will work perfectly well with key objects

 * whose <tt>equals</tt> methods are not based upon object identity, such

 * as <tt>String</tt> instances.  With such recreatable key objects,

 * however, the automatic removal of <tt>WeakHashMap</tt> entries whose

 * keys have been discarded may prove to be confusing.

 *

 * <p> The behavior of the <tt>WeakHashMap</tt> class depends in part upon

 * the actions of the garbage collector, so several familiar (though not

 * required) <tt>Map</tt> invariants do not hold for this class.  Because

 * the garbage collector may discard keys at any time, a

 * <tt>WeakHashMap</tt> may behave as though an unknown thread is silently

 * removing entries.  In particular, even if you synchronize on a

 * <tt>WeakHashMap</tt> instance and invoke none of its mutator methods, it

 * is possible for the <tt>size</tt> method to return smaller values over

 * time, for the <tt>isEmpty</tt> method to return <tt>false</tt> and

 * then <tt>true</tt>, for the <tt>containsKey</tt> method to return

 * <tt>true</tt> and later <tt>false</tt> for a given key, for the

 * <tt>get</tt> method to return a value for a given key but later return

 * <tt>null</tt>, for the <tt>put</tt> method to return

 * <tt>null</tt> and the <tt>remove</tt> method to return

 * <tt>false</tt> for a key that previously appeared to be in the map, and

 * for successive examinations of the key set, the value collection, and

 * the entry set to yield successively smaller numbers of elements.

 *

 * <p> Each key object in a <tt>WeakHashMap</tt> is stored indirectly as

 * the referent of a weak reference.  Therefore a key will automatically be

 * removed only after the weak references to it, both inside and outside of the

 * map, have been cleared by the garbage collector.

 *

 * <p> <strong>Implementation note:</strong> The value objects in a

 * <tt>WeakHashMap</tt> are held by ordinary strong references.  Thus care

 * should be taken to ensure that value objects do not strongly refer to their

 * own keys, either directly or indirectly, since that will prevent the keys

 * from being discarded.  Note that a value object may refer indirectly to its

 * key via the <tt>WeakHashMap</tt> itself; that is, a value object may

 * strongly refer to some other key object whose associated value object, in

 * turn, strongly refers to the key of the first value object.  If the values

 * in the map do not rely on the map holding strong references to them, one way

 * to deal with this is to wrap values themselves within

 * <tt>WeakReferences</tt> before

 * inserting, as in: <tt>m.put(key, new WeakReference(value))</tt>,

 * and then unwrapping upon each <tt>get</tt>.

 *

 * <p>The iterators returned by the <tt>iterator</tt> method of the collections

 * returned by all of this class's "collection view methods" are

 * <i>fail-fast</i>: if the map is structurally modified at any time after the

 * iterator is created, in any way except through the iterator's own

 * <tt>remove</tt> method, the iterator will throw a {@link

 * ConcurrentModificationException}.  Thus, in the face of concurrent

 * modification, the iterator fails quickly and cleanly, rather than risking

 * arbitrary, non-deterministic behavior at an undetermined time in the future.

 *

 * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed

 * as it is, generally speaking, impossible to make any hard guarantees in the

 * presence of unsynchronized concurrent modification.  Fail-fast iterators

 * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.

 * Therefore, it would be wrong to write a program that depended on this

 * exception for its correctness:  <i>the fail-fast behavior of iterators

 * should be used only to detect bugs.</i>

 *

 * <p>This class is a member of the

 * <a href="{@docRoot}/../technotes/guides/collections/index.html">

 * Java Collections Framework</a>.

 *

 * @param <K> the type of keys maintained by this map

 * @param <V> the type of mapped values

 *

 * @author      Doug Lea

 * @author      Josh Bloch

 * @author      Mark Reinhold

 * @since       1.2

 * @see         java.util.HashMap

 * @see         java.lang.ref.WeakReference

 */

public class WeakHashMap<K,V>

    extends AbstractMap<K,V>

    implements Map<K,V> {

    /**

     * The default initial capacity -- MUST be a power of two.

     */

    private static final int DEFAULT_INITIAL_CAPACITY = 16;

    /**

     * The maximum capacity, used if a higher value is implicitly specified

     * by either of the constructors with arguments.

     * MUST be a power of two <= 1<<30.

     */

    private static final int MAXIMUM_CAPACITY = 1 << 30;

    /**

     * The load factor used when none specified in constructor.

     */

    private static final float DEFAULT_LOAD_FACTOR = 0.75f;

    /**

     * The table, resized as necessary. Length MUST Always be a power of two.

     */

    Entry<K,V>[] table;

    /**

     * The number of key-value mappings contained in this weak hash map.

     */

    private int size;

    /**

     * The next size value at which to resize (capacity * load factor).

     */

    private int threshold;

    /**

     * The load factor for the hash table.

     */

    private final float loadFactor;

    /**

     * Reference queue for cleared WeakEntries

     */

    private final ReferenceQueue<Object> queue = new ReferenceQueue<>();

    /**

     * The number of times this WeakHashMap has been structurally modified.

     * Structural modifications are those that change the number of

     * mappings in the map or otherwise modify its internal structure

     * (e.g., rehash).  This field is used to make iterators on

     * Collection-views of the map fail-fast.

     *

     * @see ConcurrentModificationException

     */

    int modCount;

    /**

     * A randomizing value associated with this instance that is applied to

     * hash code of keys to make hash collisions harder to find.

     */

    transient final int hashSeed = sun.misc.Hashing.randomHashSeed(this);

    @SuppressWarnings("unchecked")

    private Entry<K,V>[] newTable(int n) {

        return (Entry<K,V>[]) new Entry<?,?>[n];

    }

    /**

     * Constructs a new, empty <tt>WeakHashMap</tt> with the given initial

     * capacity and the given load factor.

     *

     * @param  initialCapacity The initial capacity of the <tt>WeakHashMap</tt>

     * @param  loadFactor      The load factor of the <tt>WeakHashMap</tt>

     * @throws IllegalArgumentException if the initial capacity is negative,

     *         or if the load factor is nonpositive.

     */

    public WeakHashMap(int initialCapacity, float loadFactor) {

        if (initialCapacity < 0)

            throw new IllegalArgumentException("Illegal Initial Capacity: "+

                                               initialCapacity);

        if (initialCapacity > MAXIMUM_CAPACITY)

            initialCapacity = MAXIMUM_CAPACITY;

        if (loadFactor <= 0 || Float.isNaN(loadFactor))

            throw new IllegalArgumentException("Illegal Load factor: "+

                                               loadFactor);

        int capacity = 1;

        while (capacity < initialCapacity)

            capacity <<= 1;

        table = newTable(capacity);

        this.loadFactor = loadFactor;

        threshold = (int)(capacity * loadFactor);

    }

    /**

     * Constructs a new, empty <tt>WeakHashMap</tt> with the given initial

     * capacity and the default load factor (0.75).

     *

     * @param  initialCapacity The initial capacity of the <tt>WeakHashMap</tt>

     * @throws IllegalArgumentException if the initial capacity is negative

     */

    public WeakHashMap(int initialCapacity) {

        this(initialCapacity, DEFAULT_LOAD_FACTOR);

    }

    /**

     * Constructs a new, empty <tt>WeakHashMap</tt> with the default initial

     * capacity (16) and load factor (0.75).

     */

    public WeakHashMap() {

        this(DEFAULT_INITIAL_CAPACITY, DEFAULT_LOAD_FACTOR);

    }

    /**

     * Constructs a new <tt>WeakHashMap</tt> with the same mappings as the

     * specified map.  The <tt>WeakHashMap</tt> is created with the default

     * load factor (0.75) and an initial capacity sufficient to hold the

     * mappings in the specified map.

     *

     * @param   m the map whose mappings are to be placed in this map

     * @throws  NullPointerException if the specified map is null

     * @since   1.3

     */

    public WeakHashMap(Map<? extends K, ? extends V> m) {

        this(Math.max((int) (m.size() / DEFAULT_LOAD_FACTOR) + 1,

                DEFAULT_INITIAL_CAPACITY),

             DEFAULT_LOAD_FACTOR);

        putAll(m);

    }

    // internal utilities

    /**

     * Value representing null keys inside tables.

     */

    private static final Object NULL_KEY = new Object();

    /**

     * Use NULL_KEY for key if it is null.

     */

    private static Object maskNull(Object key) {

        return (key == null) ? NULL_KEY : key;

    }

    /**

     * Returns internal representation of null key back to caller as null.

     */

    static Object unmaskNull(Object key) {

        return (key == NULL_KEY) ? null : key;

    }

    /**

     * Checks for equality of non-null reference x and possibly-null y.  By

     * default uses Object.equals.

     */

    private static boolean eq(Object x, Object y) {

        return x == y || x.equals(y);

    }

    /**

     * Retrieve object hash code and applies a supplemental hash function to the

     * result hash, which defends against poor quality hash functions.  This is

     * critical because HashMap uses power-of-two length hash tables, that

     * otherwise encounter collisions for hashCodes that do not differ

     * in lower bits.

     */

    final int hash(Object k) {

        if (k instanceof String) {

            return ((String) k).hash32();

        }

        int  h = hashSeed ^ k.hashCode();

        // This function ensures that hashCodes that differ only by

        // constant multiples at each bit position have a bounded

        // number of collisions (approximately 8 at default load factor).

        h ^= (h >>> 20) ^ (h >>> 12);

        return h ^ (h >>> 7) ^ (h >>> 4);

    }

    /**

     * Returns index for hash code h.

     */

    private static int indexFor(int h, int length) {

        return h & (length-1);

    }

    /**

     * Expunges stale entries from the table.

     */

    private void expungeStaleEntries() {

        for (Object x; (x = queue.poll()) != null; ) {

            synchronized (queue) {

                @SuppressWarnings("unchecked")

                    Entry<K,V> e = (Entry<K,V>) x;

                int i = indexFor(e.hash, table.length);

                Entry<K,V> prev = table[i];

                Entry<K,V> p = prev;

                while (p != null) {

                    Entry<K,V> next = p.next;

                    if (p == e) {

                        if (prev == e)

                            table[i] = next;

                        else

                            prev.next = next;

                        // Must not null out e.next;

                        // stale entries may be in use by a HashIterator

                        e.value = null; // Help GC

                        size--;

                        break;

                    }

                    prev = p;

                    p = next;

                }

            }

        }

    }

    /**

     * Returns the table after first expunging stale entries.

     */

    private Entry<K,V>[] getTable() {

        expungeStaleEntries();

        return table;

    }

    /**

     * Returns the number of key-value mappings in this map.

     * This result is a snapshot, and may not reflect unprocessed

     * entries that will be removed before next attempted access

     * because they are no longer referenced.

     */

    public int size() {

        if (size == 0)

            return 0;

        expungeStaleEntries();

        return size;

    }

    /**

     * Returns <tt>true</tt> if this map contains no key-value mappings.

     * This result is a snapshot, and may not reflect unprocessed

     * entries that will be removed before next attempted access

     * because they are no longer referenced.

     */

    public boolean isEmpty() {

        return size() == 0;

    }

    /**

     * Returns the value to which the specified key is mapped,

     * or {@code null} if this map contains no mapping for the key.

     *

     * <p>More formally, if this map contains a mapping from a key

     * {@code k} to a value {@code v} such that {@code (key==null ? k==null :

     * key.equals(k))}, then this method returns {@code v}; otherwise

     * it returns {@code null}.  (There can be at most one such mapping.)

     *

     * <p>A return value of {@code null} does not <i>necessarily</i>

     * indicate that the map contains no mapping for the key; it's also

     * possible that the map explicitly maps the key to {@code null}.

     * The {@link #containsKey containsKey} operation may be used to

     * distinguish these two cases.

     *

     * @see #put(Object, Object)

     */

    public V get(Object key) {

        Object k = maskNull(key);

        int h = hash(k);

        Entry<K,V>[] tab = getTable();

        int index = indexFor(h, tab.length);

        Entry<K,V> e = tab[index];

        while (e != null) {

            if (e.hash == h && eq(k, e.get()))

                return e.value;

            e = e.next;

        }

        return null;

    }

    /**

     * Returns <tt>true</tt> if this map contains a mapping for the

     * specified key.

     *

     * @param  key   The key whose presence in this map is to be tested

     * @return <tt>true</tt> if there is a mapping for <tt>key</tt>;

     *         <tt>false</tt> otherwise

     */

    public boolean containsKey(Object key) {

        return getEntry(key) != null;

    }

    /**

     * Returns the entry associated with the specified key in this map.

     * Returns null if the map contains no mapping for this key.

     */

    Entry<K,V> getEntry(Object key) {

        Object k = maskNull(key);

        int h = hash(k);

        Entry<K,V>[] tab = getTable();

        int index = indexFor(h, tab.length);

        Entry<K,V> e = tab[index];

        while (e != null && !(e.hash == h && eq(k, e.get())))

            e = e.next;

        return e;

    }

    /**

     * Associates the specified value with the specified key in this map.

     * If the map previously contained a mapping for this key, the old

     * value is replaced.

     *

     * @param key key with which the specified value is to be associated.

     * @param value value to be associated with the specified key.

     * @return the previous value associated with <tt>key</tt>, or

     *         <tt>null</tt> if there was no mapping for <tt>key</tt>.

     *         (A <tt>null</tt> return can also indicate that the map

     *         previously associated <tt>null</tt> with <tt>key</tt>.)

     */

    public V put(K key, V value) {

        Object k = maskNull(key);

        int h = hash(k);

        Entry<K,V>[] tab = getTable();

        int i = indexFor(h, tab.length);

        for (Entry<K,V> e = tab[i]; e != null; e = e.next) {

            if (h == e.hash && eq(k, e.get())) {

                V oldValue = e.value;

                if (value != oldValue)

                    e.value = value;

                return oldValue;

            }

        }

        modCount++;

        Entry<K,V> e = tab[i];

        tab[i] = new Entry<>(k, value, queue, h, e);

        if (++size >= threshold)

            resize(tab.length * 2);

        return null;

    }

    /**

     * Rehashes the contents of this map into a new array with a

     * larger capacity.  This method is called automatically when the

     * number of keys in this map reaches its threshold.

     *

     * If current capacity is MAXIMUM_CAPACITY, this method does not

     * resize the map, but sets threshold to Integer.MAX_VALUE.

     * This has the effect of preventing future calls.

     *

     * @param newCapacity the new capacity, MUST be a power of two;

     *        must be greater than current capacity unless current

     *        capacity is MAXIMUM_CAPACITY (in which case value

     *        is irrelevant).

     */

    void resize(int newCapacity) {

        Entry<K,V>[] oldTable = getTable();

        int oldCapacity = oldTable.length;

        if (oldCapacity == MAXIMUM_CAPACITY) {

            threshold = Integer.MAX_VALUE;

            return;

        }

        Entry<K,V>[] newTable = newTable(newCapacity);

        transfer(oldTable, newTable);

        table = newTable;

        /*

         * If ignoring null elements and processing ref queue caused massive

         * shrinkage, then restore old table.  This should be rare, but avoids

         * unbounded expansion of garbage-filled tables.

         */

        if (size >= threshold / 2) {

            threshold = (int)(newCapacity * loadFactor);

        } else {

            expungeStaleEntries();

            transfer(newTable, oldTable);

            table = oldTable;

        }

    }

    /** Transfers all entries from src to dest tables */

    private void transfer(Entry<K,V>[] src, Entry<K,V>[] dest) {

        for (int j = 0; j < src.length; ++j) {

            Entry<K,V> e = src[j];

            src[j] = null;

            while (e != null) {

                Entry<K,V> next = e.next;

                Object key = e.get();

                if (key == null) {

                    e.next = null;  // Help GC