/*
 * Copyright (c) 1994, 2023, 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 Torello.Java.ReadOnly;

import java.util.*;

import java.util.function.BiConsumer;
import java.util.function.Consumer;
import java.util.function.Predicate;
import java.util.function.Function;

import Torello.Java.Additional.Tuple2;

/**
 * Immutable Wrapper for <CODE>java&#46;util&#46;Hashtable</CODE>, found in the "Java Collections
 * Framework".
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=Hashtable DATA-ENDING=table>
 * <EMBED CLASS='external-html' DATA-FILE-ID=DATA_CLASS>
 * <EMBED CLASS='external-html' DATA-FILE-ID=RO_SYNCHRONIZED>
 * 
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_MAIN")
@SuppressWarnings("unchecked")
public class ReadOnlyHashtable<K, V>
    implements ReadOnlyDictionary<K, V>, ReadOnlyMap<K, V>, Cloneable, java.io.Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Protected & Private Fields, Methods, Statics
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    // Minor Optimization where new Hashtable's that have no contents always re-use this static
    // instance.  Since this instance is completely empty, the Raw-Types things is irrelevant.

    @SuppressWarnings("rawtypes")
    private static final Hashtable EMPTY_HASH_TABLE = new Hashtable(0, 0.75f);

    // Singleton & Empty ReadOnlyHashtable, Uses the "Supplier Constructor"
    @SuppressWarnings("rawtypes")
    private static final ReadOnlyHashtable EMPTY_READONLY_HASH_TABLE =
        new ReadOnlyHashtable(EMPTY_HASH_TABLE);

    // The actual Hashtable used by this instance.
    private final Hashtable<K, V> hashTable;

    // TRUE     => This was built using the class ROHashtableBuilder
    // FALSE    => This was built using the clone() of a standard java.util.Hashtable constructor

    private final boolean fromBuilderOrHashtable;

    // Mimics the C++ Keyword/Concept of "Friend Class".   Is "Friends With" ROHashtableBuilder
    static class AccessBadge { private AccessBadge() { } }
    private static final AccessBadge friendClassBadge = new AccessBadge();


    // ********************************************************************************************
    // ********************************************************************************************
    // Builder, Acess-Badge Constructor - and Static "Empty" getter (which is used by the builder)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns an empty, <B STYLE='color: red;'>singleton</B>, instance of
     * {@code ReadOnlyHashtable}.
     * 
     * @param <X> Returned {@link ReadOnlyMap}'s Key-Type.
     * @param <Y> Returned {@link ReadOnlyMap}'s Value-Type.  
     * 
     * @return An empty map.  Since this map is both empty &amp; read-only, a raw-type singleton 
     * will suffice for all operations offered by this clas.
     */
    public static <X, Y> ReadOnlyHashtable<X, Y> emptyROHT()
    { return (ReadOnlyHashtable<X, Y>) EMPTY_READONLY_HASH_TABLE; }

    // Used by the **Builder**
    // To all the readers out there following along: The "AccessBadge" thing is just a slightly
    // wimpier substitute for the C++ keyword / concept 'friend' or "Friend Class".  It means this
    // constructor is (for all intents and purposes) a private-constructor, except for the class
    // ROHashtableBuilder
    //
    // This is the Constructor used by the Builder.  It has a "Zero-Size" Optimization

    ReadOnlyHashtable(ROHashtableBuilder<K, V> rohtb, ROHashtableBuilder.AccessBadge badge)
    {
        Objects.requireNonNull(badge, "Access Badge is null.  Requires Friend-Class Badge");

        this.fromBuilderOrHashtable = true;
        this.hashTable = rohtb;
    }

    // SPECIAL CASE: ReadOnlyProperties inherits ReadOnlyHashtable
    // NOTE:         ROPropertiesBuilder **DOES NOT** inherit ROHashtableBuilder
    //
    // The parent class of ReadOnlyProperties (a.k.a. this class) is completely unused, and the
    // private fields are not important.  For inheritance purposes, though, this is the parent
    // class, and as such, it has to be initialized with something!

    ReadOnlyHashtable(ReadOnlyProperties.AccessBadge badge)
    {
        this.fromBuilderOrHashtable = true; // This is unused
        this.hashTable = null;              // This is unused
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Modified-Original Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Copies the contents of parameter {@code 'map'}, and saves saves it, thereby guaranteeing
     * {@code 'this'} instance is Read-Only and fully-shielded from outside modification.
     * 
     * @param map The {@code map} to be copied into {@code 'this'} instance internal and private
     * {@code 'hashTable'} field.
     */
    public ReadOnlyHashtable(Map<K, V> map)
    {
        this.fromBuilderOrHashtable = false;

        this.hashTable = (map.size() == 0)
            ? ((Hashtable<K, V>) EMPTY_HASH_TABLE)
            : new Hashtable<>(map);
    }

    /**
     * If only a small amount of processing needs to be done on the contents of some Java
     * Map, and using an entire Builder-Class seems disproportionately complex - <I>this
     * constructor can convert any Java {@code Map} into a {@code ReadOnlyHashtable}, using
     * a simple {@code 'mapTranslator'}</I>.
     * 
     * @param <X> The Key-Type of the User-Provided {@code Map}.
     * @param <Y> The Value-Type of the User-Provided {@code Map}.
     * 
     * @param refHolder This must a non-null instance of {@link Tuple2}.  The provided
     * {@code Consumer} is just that, a {@code 'Consumer'} rather than a {@code 'Function'}, since
     * the results of each translation must be assigned to the values inside this tuple in order
     * for them to be inserted into this {@code ReadOnlyHashtable}.
     * 
     * @param map Any Java {@code Map}.
     * 
     * @param mapTranslator A consumer for mapping the iterated elements of Map-Types {@code 'X'}
     * and {@code 'Y'}, into the actual {@code Hashtable's} Key-Type {@code 'K'}, and Value-Type
     * {@code 'V'}.  The results of this translation must be placed into the fields inside
     * {@code 'refHolder'}.
     * 
     * <BR /><BR />If this parameter is passed null, this method will throw a
     * {@code NullPointerException}.
     * 
     * @param filter An optional filter that can be used to prevent &amp; prohibit any chosen
     * elements from input {@code 'map'} from being inserted into {@code 'this'}
     * {@code ReadOnlyTreeMap}.
     * 
     * <BR /><BR />This parameter may be passed null, and if it is, it will be silently ignored, 
     * and all entries present inside {@code 'map'} will be processed and inserted into
     * {@code 'this'}
     * 
     * @param loadFactor <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * 
     * @throws NullPointerException if either parameter {@code 'i'} or parameter 
     * {@code 'mapTranslator'} is passed null.
     */
    public <X, Y> ReadOnlyHashtable(
            Tuple2<K, V>                refHolder,
            Map<X, Y>                   map,
            Consumer<Map.Entry<X, Y>>   mapTranslator,
            Predicate<Map.Entry<X, Y>>  filter,
            Float                       loadFactor
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(mapTranslator, ROHelpers.NULL_MSG + "'mapTranslator'");

        fromBuilderOrHashtable = false;

        Hashtable<K, V> hashTable = (loadFactor != null)
            ? new Hashtable<>(map.size(), loadFactor)
            : new Hashtable<>(map.size());

        if (filter == null)

            for (Map.Entry<X, Y> entry : map.entrySet())
            {
                mapTranslator.accept(entry);
                hashTable.put(refHolder.a, refHolder.b);
            }

        else for (Map.Entry<X, Y> entry : map.entrySet())
        {
            if (! filter.test(entry)) continue;
            mapTranslator.accept(entry);
            hashTable.put(refHolder.a, refHolder.b);
        }

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.hashTable = (hashTable.size() == 0)
            ? ((Hashtable<K, V>) EMPTY_HASH_TABLE)
            : hashTable;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // New Stuff, January 2024
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Constructs an instance of {@code ReadOnlyHashtable} that contains the keys present in
     * parameter {@code 'keys'}, and values generated by {@code 'valueMapper'} - using each of the
     * {@code 'keys'} as input.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LOOK_AT_IT>
     * 
     * @param keys          Any Java {@code Iterable} instance.
     * @param valueMapper   A user provided function to compute a map value, based on a map key.
     * @param filter        <EMBED CLASS='external-html' DATA-FILE-ID=MAP_ITERABLE_FILTER>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=MAP_TABLE_ICAPACITY>
     *  
     * @throws NullPointerException if either {@code 'keys'} or {@code 'valueMapper'} are passed
     * null.
     */
    public ReadOnlyHashtable(
            Iterable<? extends K>               keys,
            Function<? super K, ? extends V>    valueMapper,
            Predicate<? super K>                filter,
            Float                               loadFactor,
            Integer                             sizeIfKnown
        )
    {
        Objects.requireNonNull(keys, ROHelpers.NULL_MSG + "'keys'");
        Objects.requireNonNull(valueMapper, ROHelpers.NULL_MSG + "'valueMapper'");

        fromBuilderOrHashtable = false;

        Hashtable<K, V> hashTable = new Hashtable<>(
            ((sizeIfKnown == null)  ? 16    : sizeIfKnown),
            ((loadFactor == null)   ? 0.75f : loadFactor)
        );

        if (filter == null)
            for (K key : keys)
                hashTable.put(key, valueMapper.apply(key));

        else
            for (K key : keys)
                if (filter.test(key))
                    hashTable.put(key, valueMapper.apply(key));

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.hashTable = (hashTable.size() == 0)
            ? ((Hashtable<K, V>) EMPTY_HASH_TABLE)
            : hashTable;
    }

    /**
     * Constructs an instance of {@code ReadOnlyHashtable} that has been populated by the Key-Value
     * Pairs left in {@code 'refHolder'} by each invocation of the {@code Runnable} parameter
     * {@code 'computeNextEntry'}.  Key-Value Pairs are inserted until an invocation of the 
     * {@code Runnable} leaves null in {@code refHolder.a} and {@code refHolder.b}
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LOOK_AT_IT>
     * 
     * @param refHolder         <EMBED CLASS='external-html' DATA-FILE-ID=REF_HOLDER>
     * @param computeNextEntry  <EMBED CLASS='external-html' DATA-FILE-ID=COMPUTE_NEXT_RUN>
     * @param loadFactor        <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param sizeIfKnown       <EMBED CLASS='external-html' DATA-FILE-ID=MAP_TABLE_ICAPACITY>
     *  
     * @throws NullPointerException if either {@code 'refHolder'} or {@code 'computeNextEntry'} are
     * passed null.
     */
    public ReadOnlyHashtable(
            Tuple2<K, V>    refHolder,
            Runnable        computeNextEntry,
            Float           loadFactor,
            Integer         sizeIfKnown
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

        fromBuilderOrHashtable = false;

        Hashtable<K, V> hashTable = new Hashtable<>(
            ((sizeIfKnown == null)  ? 16    : sizeIfKnown),
            ((loadFactor == null)   ? 0.75f : loadFactor)
        );

        do
        {
            computeNextEntry.run();
            if ((refHolder.a == null) && (refHolder.b == null)) break;
            hashTable.put(refHolder.a, refHolder.b);
        }
        while (true);

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.hashTable = (hashTable.size() == 0)
            ? ((Hashtable<K, V>) EMPTY_HASH_TABLE)
            : hashTable;
    }

    /**
     * Populates an instance of {@code ReadOnlyHashtable} by iterating the input {@code 'source'}
     * iterable, and passing each value returned by that {@code Iterator} to the
     * {@code 'computeNextEntry'} Java {@code Consumer}.
     * 
     * <BR /><BR />It is the programmer's responsibility to properly place each Key-Value Pair 
     * that is intending to be inserted into the final {@code Map} instance into the
     * {@code 'refHolder'} instance.  After each invocation of {@code 'computeNextEntry'}, this 
     * constructor's logic will retrieve the values within {@code 'refHolder.a'} and
     * {@code 'refHolder.b'} and insert them into this instance internal {@code Hashtable}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LOOK_AT_IT>
     * 
     * @param <X>               The type of the elements inside {@code 'source'}
     * @param source            Any Java {@code Iterable} instance.
     * @param refHolder         <EMBED CLASS='external-html' DATA-FILE-ID=REF_HOLDER>
     * @param computeNextEntry  <EMBED CLASS='external-html' DATA-FILE-ID=COMPUTE_NEXT_CONS>
     * @param filter            May be used to filter out some of the elements of {@code 'source'}
     * @param loadFactor        <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param sizeIfKnown       <EMBED CLASS='external-html' DATA-FILE-ID=MAP_TABLE_ICAPACITY>
     * 
     * @throws NullPointerException if either {@code 'refHolder'}, {@code 'computeNextEntry'} or
     * {@code 'source'} are passed null.
     */
    public <X> ReadOnlyHashtable(
            Iterable<X>             source,
            Tuple2<K, V>            refHolder,
            Consumer<? super X>     computeNextEntry,
            Predicate<? super X>    filter,
            Float                   loadFactor,
            Integer                 sizeIfKnown
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

        fromBuilderOrHashtable = false;

        Hashtable<K, V> hashTable = new Hashtable<>(
            ((sizeIfKnown == null)  ? 16    : sizeIfKnown),
            ((loadFactor == null)   ? 0.75f : loadFactor)
        );

        X x; // temp var
        Iterator<X> iter = source.iterator();

        if (filter == null)

            while (iter.hasNext())
            {
                computeNextEntry.accept(iter.next());
                hashTable.put(refHolder.a, refHolder.b);
            }

        else

            while (iter.hasNext())
                if (filter.test(x = iter.next()))
                {
                    computeNextEntry.accept(x);
                    hashTable.put(refHolder.a, refHolder.b);
                }

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.hashTable = (hashTable.size() == 0)
            ? ((Hashtable<K, V>) EMPTY_HASH_TABLE)
            : hashTable;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Array Constructors, March 2024
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieves elements from the VarArgs Generic-Array parameter {@code 'elements'}, and
     * subsequently invokes the {@code 'computeNextEntry'} processor to populate this
     * {@code ReadOnlyHashtable}.
     * 
     * @param <X>                  The type of array parameter {@code 'elements'}
     * @param refHolder            <EMBED CLASS='external-html' DATA-FILE-ID=REF_HOLDER>
     * @param computeNextEntry     <EMBED CLASS='external-html' DATA-FILE-ID=ARR_COMPUTE_NEXT_CONS>
     * @param filter               <EMBED CLASS='external-html' DATA-FILE-ID=MAP_ARRAY_FILTER>
     * @param loadFactor           <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param elements             Any Generic VarArgs-Array
     * @throws ClassCastException  <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CCEX>
     * 
     * @throws NullPointerException if either {@code 'refHolder'} or {@code 'computeNextEntry'}
     * are passed null
     */
    public <X> ReadOnlyHashtable(
            Tuple2<K, V>            refHolder,
            Consumer<? super X>     computeNextEntry,
            Predicate<? super X>    filter,
            Float                   loadFactor,
            X...                    elements
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

        this.fromBuilderOrHashtable = false;

        Hashtable<K, V> hashTable =
            new Hashtable<>(elements.length, ((loadFactor == null) ? 0.75f : loadFactor));

        if (filter == null) for (X e : elements)
        {
            computeNextEntry.accept(e);
            hashTable.put(refHolder.a, refHolder.b);
        }

        else for (X x : elements) if (filter.test(x))
        {
            computeNextEntry.accept(x);
            hashTable.put(refHolder.a, refHolder.b);
        }

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.hashTable = (hashTable.size() == 0)
            ? ((Hashtable<K, V>) EMPTY_HASH_TABLE)
            : hashTable;
    }

    /**
     * Retrieves elements from the Java Primitive-Array parameter {@code 'primitiveArray'}, and
     * subsequently invokes the {@code 'computeNextEntry'} processor to populate this
     * {@code ReadOnlyHashtable}.
     * 
     * @param filter               <EMBED CLASS='external-html' DATA-FILE-ID=PRED_FILT_PRIM>
     * @param computeNextEntry     <EMBED CLASS='external-html' DATA-FILE-ID=ARR_COMPUTE_NEXT_CONS>
     * @param refHolder            <EMBED CLASS='external-html' DATA-FILE-ID=REF_HOLDER>
     * @param loadFactor           <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param primitiveArray       Any Java Primitive-Array
     * @throws ClassCastException  <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CCEX>
     * 
     * @throws NullPointerException if either {@code 'refHolder'} or {@code 'computeNextEntry'}
     * are passed null
     * 
     */
    public <X> ReadOnlyHashtable(
            Predicate<?>    filter,
            Consumer<?>     computeNextEntry,
            Tuple2<K, V>    refHolder,
            Float           loadFactor,
            Object          primitiveArray
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

        this.fromBuilderOrHashtable = false;

        Hashtable<K, V> hashTable = ROHelpers.buildROMap(
            primitiveArray,
            (int arrayLen) -> new Hashtable<>(arrayLen, ((loadFactor == null) ? 0.75f : loadFactor)),
            filter,
            refHolder,
            computeNextEntry
        );

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.hashTable = (hashTable.size() == 0)
            ? ((Hashtable<K, V>) EMPTY_HASH_TABLE)
            : hashTable;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Convert to java.util Types
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Clone's {@code 'this'} instance internal {@code Hashtable<K, V>} field, and returns it. 
     * <EMBED CLASS='external-html' DATA-TYPE=Hashtable DATA-FILE-ID=CLONE_TO>
     * 
     * @return An independent, mutable copy of {@code 'this'} instance internal
     * {@code Hashtable<K, V>} data-structure.
     */
    public Hashtable<K, V> cloneToHashtable()
    {
        if (! fromBuilderOrHashtable) return (Hashtable<K, V>) this.hashTable.clone();

        Hashtable<K, V> ret = new Hashtable<K, V>();

        for (Map.Entry<K, V> e :
            ((ROHashtableBuilder<K, V>) this.hashTable)._entrySet(friendClassBadge))

            ret.put(e.getKey(), e.getValue());

        return ret;
    }

    /**
     * Invokes {@code java.util.Collections.unmodifiableMap} on the internal {@code Hashtable}.
     * <EMBED CLASS='external-html' DATA-RET_TYPE=Map DATA-FILE-ID=WRAP_TO_IMMUTABLE>
     * 
     * @return A {@code Map} which adheres to the JDK interface {@code java.util.Map}, but throws
     * an {@code UnsupportedOperationException} if a user attempts to invoke a Mutator-Method on
     * the returned instance.
     */
    public Map<K, V> wrapToImmutableMap()
    { return Collections.unmodifiableMap(this.hashTable); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Methods, java.util.Hashtable
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns the number of keys in this {@code Hashtable}.
     * @return  the number of keys in this {@code Hashtable}.
     */
    public int size()
    { return this.hashTable.size(); }

    /**
     * Tests if this {@code Hashtable} maps no keys to values.
     * 
     * @return  {@code TRUE} if this {@code Hashtable} maps no keys to values; {@code FALSE}
     * otherwise.
     */
    public boolean isEmpty()
    { return this.hashTable.isEmpty(); }

    /**
     * Returns an enumeration of the keys in this {@code Hashtable}.  Use the Enumeration methods
     * on the returned object to fetch the keys sequentially.
     * 
     * @return  an enumeration of the keys in this {@code Hashtable}.
     * 
     * @see #elements()
     * @see #keySet()
     * @see ReadOnlyMap
     */
    public Enumeration<K> keys()
    { return this.hashTable.keys(); }

    /**
     * Returns an enumeration of the values in this {@code Hashtable}.  Use the Enumeration methods
     * on the returned object to fetch the elements sequentially.
     * 
     * @return  an enumeration of the values in this {@code Hashtable}.
     * 
     * @see #keys()
     * @see #values()
     * @see ReadOnlyMap
     */
    public Enumeration<V> elements()
    { return this.hashTable.elements(); }

    /**
     * Tests if some key maps into the specified value in this {@code Hashtable}.  This operation
     * is more expensive than the {@link #containsKey containsKey} method.
     *
     * <BR /><BR />Note that this method is identical in functionality to
     * {@link #containsValue containsValue}, (which is part of the {@link ReadOnlyMap} interface.
     *
     * @param value a value to search for
     * 
     * @return {@code TRUE} if and only if some key maps to the {@code value} argument in this
     * {@code Hashtable} as determined by the {@code equals} method; {@code false} otherwise.
     * 
     * @throws NullPointerException if the value is {@code null}
     */
    public boolean contains(Object value)
    { return this.hashTable.contains(value); }

    /**
     * Returns {@code TRUE} if this {@code Hashtable} maps one or more keys to this value.
     *
     * <BR /><BR />Note that this method is identical in functionality to {@link #contains}.
     *
     * @param value value whose presence in this {@code Hashtable} is to be tested
     * @return {@code TRUE} if this map maps one or more keys to the specified value
     * @throws NullPointerException  if the value is {@code null}
     */
    public boolean containsValue(Object value)
    { return this.hashTable.contains(value); }

    /**
     * Tests if the specified object is a key in this {@code Hashtable}.
     *
     * @param key possible key
     * 
     * @return {@code TRUE} if and only if the specified object is a key in this {@code Hashtable},
     * as determined by the {@code equals} method; {@code false} otherwise.
     * 
     * @throws NullPointerException  if the key is {@code null}
     * 
     * @see #contains(Object)
     */
    public boolean containsKey(Object key)
    { return this.hashTable.containsKey(key); }

    /**
     * Returns the value to which the specified key is mapped, or {@code null} if this map contains
     * no mapping for the key.
     *
     * <BR /><BR />More formally, if this map contains a mapping from a key {@code k} to a value
     * {@code v} such that {@code (key.equals(k))}, then this method returns {@code v}; otherwise
     * it returns {@code null}.  (There can be at most one such mapping.)
     *
     * @param key the key whose associated value is to be returned
     * 
     * @return the value to which the specified key is mapped, or {@code null} if this map contains
     * no mapping for the key
     * 
     * @throws NullPointerException if the specified key is null
     */
    public V get(Object key)
    { return this.hashTable.get(key); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Views
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a {@link ReadOnlySet} view of the keys contained in this map.  The set is backed by
     * the map, so changes to the map are reflected in the set, and vice-versa.
     */
    public ReadOnlySet<K> keySet()
    {
        return InterfaceBuilder.toReadOnlySet(
            fromBuilderOrHashtable
                ? ((ROHashtableBuilder<K, V>) this.hashTable)._keySet(friendClassBadge)
                : this.hashTable.keySet()
        );
    }

    /** Returns a {@link ReadOnlySet} view of the mappings contained in this map. */
    public ReadOnlySet<ReadOnlyMap.Entry<K, V>> entrySet()
    {
        return ROHelpers.toReadOnlyEntrySet(
            fromBuilderOrHashtable
                ? ((ROHashtableBuilder<K, V>) this.hashTable)._entrySet(friendClassBadge)
                : this.hashTable.entrySet()
        );
    }

    /** Returns a {@link ReadOnlyCollection} view of the values contained in this map. */
    public ReadOnlyCollection<V> values()
    {
        return InterfaceBuilder.toReadOnlyCollection(
            fromBuilderOrHashtable
                ? ((ROHashtableBuilder<K, V>) this.hashTable)._values(friendClassBadge)
                : this.hashTable.values()
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Comparison and hashing
    // ********************************************************************************************
    // ********************************************************************************************


    public V getOrDefault(Object key, V defaultValue)
    { return this.hashTable.getOrDefault(key, defaultValue); }

    public void forEach(BiConsumer<? super K, ? super V> action)
    { this.hashTable.forEach(action); }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a string representation of this {@code Hashtable} object in the form of a set of
     * entries, enclosed in braces and separated by the ASCII characters {@code " , "} (comma and
     * space). Each entry is rendered as the key, an equals sign {@code '='}, and the associated
     * element, where the {@code toString} method is used to convert the key and element to
     * {@code String's}.
     * 
     * @return a {@code String} representation of this {@code Hashtable}
     */
    public String toString()
    {
        return ROHelpers.toString(
            this.hashTable, // if the map contains itself, it is needed for printing purposes
            fromBuilderOrHashtable
                ? ((ROHashtableBuilder<K, V>) this.hashTable)._entrySet(friendClassBadge)
                : this.hashTable.entrySet()
        );
    }

    /**
     * Compares the specified Object with this Map for equality, as per the definition in the 
     * class {@code java.util.Hashtable}.
     *
     * @param  o object to be compared for equality with this {@code ReadOnlyHashtable}.
     * @return {@code TRUE} if the specified Object is equal to this Map
     */
    public boolean equals(Object o)
    { return ROHelpers.roMapEq(this, o); }

    /**
     * Returns the hash code value for this Map as per the definition in the class
     * {@code java.util.Hashtable}.
     */
    public int hashCode() 
    { return this.hashTable.hashCode(); }
}