/*
 * Copyright (c) 1997, 2016, 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.lang.ref;


/**
 * {@code Ephemeron<K, V>} objects are a special kind of {@code WeakReference<K>}
 * objects, which hold two referents (a normal referent, also called a key referent,
 * and a value referent) and do not prevent their referents from being made
 * finalizable, finalized, and then  reclaimed. In addition to the key referent,
 * which adheres to the referent behavior of a {@code WeakReference<K>},
 * an ephemeron also holds a value referent whose reachabiliy strength is affected
 * by the reachability strength of the key referent. The value referent of an
 * Ephemeron instance is considered:
 * <ul>
 * <li><em>strongly reachable</em> if the key referent of the same Ephemeron
 * object is strongly reachable, or if the value referent is otherwise strongly
 * reachable.
 * </li>
 * <li><em>softly reachable</em> if it is not strongly reachable, and the key referent of
 * the same Ephemeron object is softly reachable, or if the value referent is
 * otherwise softly reachable.
 * </li>
 * <li><em>weakly reachable</em> if it is neither strongly nor softly reachable, and the
 * key referent of the same Ephemeron object is weakly reachable, or if the value
 * referent is otherwise  weakly reachable.
 * </li>
 * </ul>
 * <p>When the collector clears an Ephemeron object instance (according to the rules
 * expressed for clearing WeakReference object instances), the Ephemeron instance's
 * key referent and value referent are simultaneously and atomically cleared.
 * <p>By convenience, the Ephemeron's normal referent is also called the key referent,
 * and can be obtained either by invoking {@link #get} or {@link #getKey} while
 * the value referent can be obtained by invoking {@link #getValue} method.
 * <h3>Reachability (should be moved to package-level docs)</h3>
 * Going from strongest to weakest, the different levels of
 * reachability reflect the life cycle of an object.  They are
 * operationally defined as follows:
 * <ul>
 * <li>An object is <em>strongly reachable</em> if it can be reached by some thread
 * without traversing any reference objects, or by traversing the value of an Ephemeron
 * whose key is strongly reachable. A newly-created object is strongly reachable by
 * the thread that created it
 * </li>
 * <li>An object is <em>softly reachable</em> if it is not strongly reachable but
 * can be reached by traversing a soft reference or by traversing the value of an
 * Ephemeron whose key is softly reachable.
 * </li>
 * <li>An object is <em>weakly reachable</em> if it is neither strongly nor softly
 * reachable but can be reached by traversing a weak reference or by traversing the
 * value of an ephemeron whose key is weakly reachable. When the weak references
 * to a weakly-reachable object are cleared, the object becomes eligible for
 * finalization.
 * </li>
 * <li>An object is <em>phantom reachable</em> if it is neither
 * strongly, softly, nor weakly reachable, it has been finalized, and
 * some phantom reference refers to it.
 * </li>
 * <li>Finally, an object is <em>unreachable</em>, and therefore
 * eligible for reclamation, when it is not reachable in any of the
 * above ways.
 * </li>
 * </ul>
 *
 * @since 9
 */

public class Ephemeron<K, V> extends WeakReference<K> {

    /**
     * The value field is treated specially by GC
     */
    private V value;

    /**
     * Creates a new ephemeron that refers to the given key and
     * given value. The new ephemeron is not registered with any queue.
     *
     * @param key   the key (or referent) the new ephemeron will refer to
     * @param value the value the new ephemeron will hold until cleared
     */
    public Ephemeron(K key, V value) {
        super(key);
        this.value = value;
    }

    /**
     * Creates a new ephemeron that refers to the given key and
     * given value and is registered with the given queue.
     *
     * @param key   the key (or referent) the new ephemeron will refer to
     * @param value the value the new ephemeron will hold until cleared
     * @param q     the queue with which the ephemeron is to be registered,
     *              or {@code null} if registration is not required
     */
    public Ephemeron(K key, V value, ReferenceQueue<? super K> q) {
        super(key, q);
        this.value = value;
    }

    /**
     * Returns this ephemeron object's referent, also known as the key.
     * If this ephemeron object has been cleared, either by the program or by
     * the garbage collector, then this method returns <code>null</code>.
     *
     * @return The key object to which this ephemeron object refers, or
     * <code>null</code> if this ephemeron object has been cleared
     * @see #getValue()
     */
    public K getKey() {
        return get();
    }

    /**
     * Returns this ephemeron object's value.
     * If this ephemeron object has been cleared, either by the program or by
     * the garbage collector, then this method returns <code>null</code>.
     *
     * @return The value object to which this ephemeron object refers, or
     * <code>null</code> if this ephemeron object has been cleared
     * @see #getKey()
     */
    public V getValue() {
        return value;
    }

    /**
     * Clears this ephemeron object, resetting both the key and
     * the value to null.  Invoking this method will not cause this
     * ephemeron object to be enqueued.
     * <p> This method is invoked only by Java code; when the garbage collector
     * clears ephemerons it does so directly, without invoking this method.
     */
    @Override
    public void clear() {
        super.clear();
        this.value = null;
    }
}