/*
 * Copyright (c) 1997, 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.io.Serializable;

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;

import java.util.*;

/**
 * Immutable Wrapper for <CODE>java&#46;util&#46;HashMap</CODE>, found in the "Java Collections
 * Framework".
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=HashMap DATA-ENDING=Map>
 * <EMBED CLASS='external-html' DATA-FILE-ID=DATA_CLASS>
 * 
 * @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 ReadOnlyHashMap<K, V> implements ReadOnlyMap<K, V>, Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Protected & Private Fields, Methods, Statics
    // ********************************************************************************************
    // ********************************************************************************************


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

    // Minor Optimization where new HashMap'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 HashMap EMPTY_HASH_MAP = new HashMap(0, 0.75f);

    // Singleton & Empty ReadOnlyHashMap, Uses the "Supplier Constructor"
    @SuppressWarnings("rawtypes")
    private static final ReadOnlyHashMap EMPTY_READONLY_HASH_MAP =
        new ReadOnlyHashMap(EMPTY_HASH_MAP);

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

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

    private final boolean fromBuilderOrHashMap;

    // Mimics the C++ Keyword/Concept of "Friend Class".   Is "Friends With" ROHashMapBuilder
    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 ReadOnlyHashMap}.
     * @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> ReadOnlyHashMap<X, Y> emptyROHM()
    { return (ReadOnlyHashMap<X, Y>) EMPTY_READONLY_HASH_MAP; }

    // 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
    // ROHashMapBuilder
    //
    // This is the Constructor used by the Builder.  It has a "Zero-Size" Optimization

    ReadOnlyHashMap(ROHashMapBuilder<K, V> rohmb, ROHashMapBuilder.AccessBadge badge)
    {
        Objects.requireNonNull(badge, "Access Badge is null.  Requires Friend-Class Badge");

        fromBuilderOrHashMap = true;
        this.hashMap = rohmb;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // 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 'hashMap'} field.
     */
    public ReadOnlyHashMap(Map<K, V> map)
    {
        fromBuilderOrHashMap = false;

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.hashMap = (map.size() == 0) ? ((HashMap<K, V>) EMPTY_HASH_MAP) : new HashMap<>(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 ReadOnlyHashMap}, 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 ReadOnlyHashMap}.
     * 
     * @param map Any Java {@code Map}.
     * 
     * @param mapTranslator A function for mapping the iterated elements of Map-Types {@code 'X'}
     * and {@code 'Y'}, into the actual {@code HashMap'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.
     * 
     * @throws IllegalArgumentException if the load factor is nonpositive
     */
    public <X, Y> ReadOnlyHashMap(
            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'");

        fromBuilderOrHashMap = false;

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

        if (filter != null)

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

        else

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

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


    // ********************************************************************************************
    // ********************************************************************************************
    // New Constructors, January 2024
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Constructs an instance of {@code ReadOnlyHashMap} 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 ReadOnlyHashMap(
            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'");

        fromBuilderOrHashMap = false;

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

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

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

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

    /**
     * Constructs an instance of {@code ReadOnlyHashMap} 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 ReadOnlyHashMap(
            Tuple2<K, V>    refHolder,
            Runnable        computeNextEntry,
            Float           loadFactor,
            Integer         sizeIfKnown
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

        fromBuilderOrHashMap = false;

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

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

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

    /**
     * Populates an instance of {@code ReadOnlyHashMap} 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 HashMap}.
     * 
     * <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            <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 'refHolder'}, {@code 'computeNextEntry'} or
     * {@code 'source'} are passed null.
     */
    public <X> ReadOnlyHashMap(
            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'");

        fromBuilderOrHashMap = false;

        HashMap<K, V> hashMap = new HashMap<>(
            ((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());
                hashMap.put(refHolder.a, refHolder.b);
            }

        else

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

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


    // ********************************************************************************************
    // ********************************************************************************************
    // 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 ReadOnlyHashMap}.
     * 
     * @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> ReadOnlyHashMap(
            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.fromBuilderOrHashMap = false;

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

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

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

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

    /**
     * Retrieves elements from the Java Primitive-Array parameter {@code 'primitiveArray'}, and
     * subsequently invokes the {@code 'computeNextEntry'} processor to populate this
     * {@code ReadOnlyHashMap}.
     * 
     * @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> ReadOnlyHashMap(
            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.fromBuilderOrHashMap = false;

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

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


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


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

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

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

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

        return ret;
    }

    /**
     * Invokes {@code java.util.Collections.unmodifiableMap} on the internal {@code HashMap}.
     * <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.hashMap); }


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


    /**
     * Returns the number of key-value mappings in this map.
     * @return the number of key-value mappings in this map
     */
    public int size()
    { return this.hashMap.size(); }

    /**
     * Returns {@code TRUE} if this map contains no key-value mappings.
     * @return {@code TRUE} if this map contains no key-value mappings
     */
    public boolean isEmpty()
    { return this.hashMap.isEmpty(); }

    /**
     * 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==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.)
     *
     * <BR /><BR />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.
     */
    public V get(Object key)
    { return this.hashMap.get(key); }

    /**
     * Returns {@code TRUE} if this map contains a mapping for the specified key.
     * @param key The key whose presence in this map is to be tested
     * @return {@code TRUE} if this map contains a mapping for the specified key.
     */
    public boolean containsKey(Object key)
    { return this.hashMap.containsKey(key); }

    /**
     * Returns {@code TRUE} if this map maps one or more keys to the specified value.
     * @param value value whose presence in this map is to be tested
     * @return {@code TRUE} if this map maps one or more keys to the specified value
     */
    public boolean containsValue(Object value)
    { return this.hashMap.containsValue(value); }


    // ********************************************************************************************
    // ********************************************************************************************
    // The Builder AccessDenied Issue
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a {@link ReadOnlySet} view of the keys contained in this map. 
     * @return a set view of the keys contained in this map
     */
    public ReadOnlySet<K> keySet()
    {
        return InterfaceBuilder.toReadOnlySet(
            fromBuilderOrHashMap
                ? ((ROHashMapBuilder<K, V>) this.hashMap)._keySet(friendClassBadge)
                : this.hashMap.keySet()
        );
    }

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

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


    // ********************************************************************************************
    // ********************************************************************************************
    // Overrides of JDK8 Map extension methods / ReadOnlyMap
    // ********************************************************************************************
    // ********************************************************************************************


    @Override
    public V getOrDefault(Object key, V defaultValue)
    { return this.hashMap.getOrDefault(key, defaultValue); }

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


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


    /**
     * Returns a {@code String} representation of this map. The {@code String} representation
     * consists of a list of key-value mappings in the order returned by the map's entrySet view's
     * iterator, enclosed in braces ({@code "{}"}). Adjacent mappings are separated by the
     * characters {@code ", "} (comma and space).  Each key-value mapping is rendered as the key
     * followed by an equals sign ({@code "="}) followed by the associated value.  Keys and values
     * are converted to {@code String's} as by {@code String.valueOf(Object)}.
     * 
     * @return a {@code String} representation of this {@code HashMap} 
     */
    public String toString()
    {
        return ROHelpers.toString(
            this.hashMap, // if the map contains itself, it is needed for printing purposes
            fromBuilderOrHashMap
                ? ((ROHashMapBuilder<K, V>) this.hashMap)._entrySet(friendClassBadge)
                : this.hashMap.entrySet()
        );
    }

    /**
     * Compares the specified Object with this Map for equality, as per the definition in the 
     * class {@code java.util.HashMap}.
     *
     * @param  o object to be compared for equality with this {@code ReadOnlyHashMap}.
     * @return 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.HashMap}.
     */
    public int hashCode() 
    { return this.hashMap.hashCode(); }
}