/*
 * 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.util.*;

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

/**
 * A Copy of Java's {@code HashMap} class; used for building a {@link ReadOnlyHashMap}.
 * Maintains <I>an internal and inaccessible {@code HashMap<E>} instance</I>.  
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=HashMap>
 * <EMBED CLASS='external-html' DATA-A_AN=a DATA-FILE-ID=BUILDERS>
 * 
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 * @see ReadOnlyHashMap
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_BUILDER")
public final class ROHashMapBuilder<K, V>
    extends HashMap<K, V>
    implements Cloneable, java.io.Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Fields & Builder Stuff
    // ********************************************************************************************
    // ********************************************************************************************


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

    // Exception messages need this
    private static final String ROHM = "HashMap";

    private boolean built = false;

    // Mimics the C++ Concept of "Friend Class".  This badge is utilized by the "build()" method
    // directly below this inner-class declaration.  It is the only place where this declaration is
    // actually used anywhere.  This prohibits access to the constructor that is used to anybody
    // else

    static class AccessBadge { private AccessBadge() { } }
    private static final AccessBadge friendClassBadge = new AccessBadge();

    /**
     * Simply transfers {@code 'this'} instance' internal {@code HashMap} to the
     * {@code ReadOnlyHashMap} Wrapper-Class.
     * 
     * @return a newly constructed {@code ReadOnlyHashMap} "Wrapper-Class", shielding the internal
     * {@code 'hashMap'} private-field from any modification.
     */
    public ReadOnlyHashMap<K, V> build()
    {
        this.built = true;

        return (size() == 0)
            ? ReadOnlyHashMap.emptyROHM()
            : new ReadOnlyHashMap<>(this, friendClassBadge);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Modified Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Constructs an empty {@code ROHashMapBuilder} with the specified initial capacity and load
     * factor.
     * 
     * <BR /><BR />To create a {@code ROHashMapBuilder} with an initial capacity that accommodates
     * an expected number of mappings, use {@link #newROHashMapBuilder(int) newROHashMapBuilder}.
     * 
     * @param initialCapacity the initial capacity
     * @param loadFactor the load factor
     * @throws IllegalArgumentException if the initial capacity is negative or the load factor is
     * nonpositive
     */
    public ROHashMapBuilder(int initialCapacity, float loadFactor)
    { super(initialCapacity, loadFactor); }

    /**
     * Constructs an empty {@code ROHashMapBuilder} with the specified initial capacity and the
     * default load factor (0.75).
     * 
     * <BR /><BR />To create a {@code ROHashMapBuilder} with an initial capacity that accommodates
     * an expected number of mappings, use {@link #newROHashMapBuilder(int) newROHashMapBuilder}.
     *
     * @param  initialCapacity the initial capacity.
     * @throws IllegalArgumentException if the initial capacity is negative.
     */
    public ROHashMapBuilder(int initialCapacity)
    { super(initialCapacity); }

    /**
     * Constructs an empty {@code ROHashMapBuilder} with the default initial capacity (16) and the
     * default load factor (0.75).
     */
    public ROHashMapBuilder()
    { super(); }

    /**
     * Constructs a new {@code ROHashMapBuilder} with the same mappings as the specified
     * {@code Map}.  The {@code ROHashMapBuilder} is created with default load factor (0.75) and an
     * initial capacity sufficient to hold the mappings in the specified {@code Map}.
     *
     * @param m the map whose mappings are to be placed in this map
     * @throws NullPointerException if the specified map is null
     */
    public ROHashMapBuilder(Map<? extends K, ? extends V> m)
    { super(m); }

    /**
     * Creates a new, empty {@code ROHashMapBuilder} suitable for the expected number of mappings.
     * The returned map uses the default load factor of 0.75, and its initial capacity is generally
     * large enough so that the expected number of mappings can be added without resizing the map.
     *
     * @param numMappings the expected number of mappings
     * @param <K> the type of keys maintained by the new map
     * @param <V> the type of mapped values
     * @return the newly created map
     * @throws IllegalArgumentException if numMappings is negative
     */
    public static <K, V> ROHashMapBuilder<K, V> newROHashMapBuilder(int numMappings)
    {
        if (numMappings < 0)
            throw new IllegalArgumentException("Negative number of mappings: " + numMappings);

        return new ROHashMapBuilder<>(calculateHashMapCapacity(numMappings));
    }

    // Copied from JDK-21, java.util.HashMap
    // Calculate initial capacity for HashMap based classes, from expected size and default load
    // factor (0.75).

    private static int calculateHashMapCapacity(int numMappings)
    { return (int) Math.ceil(numMappings / (double) /* DEFAULT_LOAD_FACTOR */ 0.75f); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Associates the specified value with the specified key in this map.  If the map previously
     * contained a mapping for the key, the old value is replaced.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @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 {@code key}, or {@code null} if there was no
     * mapping for {@code key}.  (A {@code null} return can also indicate that the map previously
     * associated {@code null} with {@code key}.)
     */
    public V put(K key, V value)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        return super.put(key, value);
    }

    /**
     * Copies all of the mappings from the specified map to this map.  These mappings will replace
     * any mappings that this map had for any of the keys currently in the specified map.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param m mappings to be stored in this map
     * @throws NullPointerException if the specified map is null
     */
    public void putAll(Map<? extends K, ? extends V> m)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        super.putAll(m);
    }

    /**
     * Removes the mapping for the specified key from this map if present.
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * @param key key whose mapping is to be removed from the map
     * 
     * @return the previous value associated with {@code key}, or {@code null} if there was no
     * mapping for {@code key}.  (A {@code null} return can also indicate that the map previously
     * associated {@code null} with {@code key}.)
     */
    public V remove(Object key)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        return super.remove(key);
    }

    /**
     * Removes all of the mappings from this map.  The map will be empty after this call returns.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     */
    public void clear()
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        super.clear();
    }


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


    /**
     * If the specified key is not already associated with a value (or is mapped to {@code null})
     * associates it with the given value and returns {@code null}, else returns the current value.
     *
     * <BR /><BR />The default implementation is equivalent to, for this {@code map}:
     *
     * <BR /><DIV CLASS=SNIP>{@code
     * V v = map.get(key);
     * 
     * if (v == null) v = map.put(key, value);
     *
     * return v;
     * }</DIV>
     *
     * <BR /><BR />The default implementation makes no guarantees about synchronization or
     * atomicity properties of this method. Any implementation providing atomicity guarantees must
     * override this method and document its concurrency properties.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @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 the specified key, or {@code null} if there was
     * no mapping for the key.  (A {@code null} return can also indicate that the map previously
     * associated {@code null} with the key, if the implementation supports null values.)
     * 
     * @throws UnsupportedOperationException if the {@code put} operation is not supported by this
     * map
     * 
     * @throws ClassCastException if the key or value is of an inappropriate type for this map
     * 
     * @throws NullPointerException if the specified key or value is null, and this map does not
     * permit null keys or values
     * 
     * @throws IllegalArgumentException if some property of the specified key or value prevents it
     * from being stored in this map
     */
    public V putIfAbsent(K key, V value)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        return super.putIfAbsent(key, value);
    }

    /**
     * Removes the entry for the specified key only if it is currently mapped to the specified
     * value.
     *
     * <BR /><BR />The default implementation is equivalent to, for this {@code map}:
     *
     * <BR /><DIV CLASS=SNIP>{@code
     * if (map.containsKey(key) && Objects.equals(map.get(key), value))
     * {
     *     map.remove(key);
     *     return true;
     * }
     * 
     * return false;
     * }</DIV>
     *
     * <BR /><BR />The default implementation makes no guarantees about synchronization or
     * atomicity properties of this method. Any implementation providing atomicity guarantees must
     * override this method and document its concurrency properties.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param key key with which the specified value is associated
     * @param value value expected to be associated with the specified key
     * @return {@code true} if the value was removed
     * 
     * @throws UnsupportedOperationException if the {@code remove} operation is not supported by
     * this map
     * 
     * @throws ClassCastException if the key or value is of an inappropriate type for this map
     * 
     * @throws NullPointerException if the specified key or value is null, and this map does not
     * permit null keys or values
     */
    public boolean remove(Object key, Object value)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        return super.remove(key, value);
    }

    /**
     * Replaces the entry for the specified key only if currently mapped to the specified value.
     *
     * <BR /><BR />The default implementation is equivalent to, for this {@code map}:
     * 
     * <DIV CLASS=SNIP>{@code
     * if (map.containsKey(key) && Objects.equals(map.get(key), oldValue))
     * {
     *     map.put(key, newValue);
     *     return true;
     * }
     * 
     * return false;
     * }</DIV>
     *
     * <BR /><BR />The default implementation does not throw {@code NullPointerException} for maps
     * that do not support null values if oldValue is null unless newValue is also null.
     *
     * <BR /><BR />The default implementation makes no guarantees about synchronization or
     * atomicity properties of this method. Any implementation providing atomicity guarantees must
     * override this method and document its concurrency properties.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param key key with which the specified value is associated
     * @param oldValue value expected to be associated with the specified key
     * @param newValue value to be associated with the specified key
     * @return {@code TRUE} if the value was replaced
     * 
     * @throws UnsupportedOperationException if the {@code put} operation is not supported by this
     * map
     * 
     * @throws ClassCastException if the class of a specified key or value prevents it from being
     * stored in this map
     * 
     * @throws NullPointerException if a specified key or newValue is null, and this map does not
     * permit null keys or values
     * 
     * @throws NullPointerException if oldValue is null and this map does not permit null values
     * 
     * @throws IllegalArgumentException if some property of a specified key or value prevents it
     * from being stored in this map
     */
    public boolean replace(K key, V oldValue, V newValue)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        return super.replace(key, oldValue, newValue);
    }

    /**
     * Replaces the entry for the specified key only if it is currently mapped to some value.
     *
     * <BR /><BR />The default implementation is equivalent to, for this {@code map}:
     *
     * <BR /><DIV CLASS=SNIP>{@code
     * if (map.containsKey(key)) return map.put(key, value);
     * return null;
     * }</DIV>
     * 
     * <BR /><BR />The default implementation makes no guarantees about synchronization or
     * atomicity properties of this method. Any implementation providing atomicity guarantees must
     * override this method and document its concurrency properties.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param key key with which the specified value is associated
     * @param value value to be associated with the specified key
     * 
     * @return the previous value associated with the specified key, or {@code null} if there was
     * no mapping for the key.  (A {@code null} return can also indicate that the map previously
     * associated {@code null} with the key, if the implementation supports null values.)
     * 
     * @throws UnsupportedOperationException if the {@code put} operation is not supported by this
     * map
     * 
     * @throws ClassCastException if the class of the specified key or value prevents it from being
     * stored in this map
     * 
     * @throws NullPointerException if the specified key or value is null, and this map does not
     * permit null keys or values
     * 
     * @throws IllegalArgumentException if some property of the specified key or value prevents it
     * from being stored in this map
     */
    public V replace(K key, V value)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        return super.replace(key, value);
    }

    /**
     * If the specified key is not already associated with a value (or is mapped to null), attempts
     * to compute its value using the given mapping function and enters it into this map unless
     * null.
     * 
     * <BR /><BR />If the mapping function returns null, no mapping is recorded. If the mapping
     * function itself throws an (unchecked) exception, the exception is rethrown, and no mapping
     * is recorded. The most common usage is to construct a new object serving as an initial mapped
     * value or memoized result, as in:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * map.computeIfAbsent(key, k -> new Value(f(k)));
     * }</DIV>
     * 
     * <BR /><BR />Or to implement a multi-value map, {@code Map<K,Collection<V>>}, supporting
     * multiple values per key:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);
     * }</DIV>
     * 
     * <BR /><BR />The mapping function should not modify this map during computation.
     * 
     * <BR /><BR />This method will, on a best-effort basis, throw a
     * {@link ConcurrentModificationException} if it is detected that the mapping function modifies
     * this map during computation.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param key key with which the specified value is to be associated
     * @param mappingFunction the mapping function to compute a value
     * 
     * @return the current (existing or computed) value associated with the specified key, or null
     * if the computed value is null
     *
     * @throws ConcurrentModificationException if it is detected that the mapping function modified
     * this map
     */
    public V computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        return super.computeIfAbsent(key, mappingFunction);
    }

    /**
     * If the value for the specified key is present and non-null, attempts to compute a new
     * mapping given the key and its current mapped value.
     * 
     * <BR /><BR />If the remapping function returns null, the mapping is removed. If the remapping
     * function itself throws an (unchecked) exception, the exception is rethrown, and the current
     * mapping is left unchanged.
     * 
     * <BR /><BR />The remapping function should not modify this map during computation.
     * 
     * <BR /><BR />This method will, on a best-effort basis, throw a
     * {@link ConcurrentModificationException} if it is detected that the remapping function
     * modifies this map during computation.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param key key with which the specified value is to be associated
     * @param remappingFunction the remapping function to compute a value
     * @return the new value associated with the specified key, or null if none
     * @throws ConcurrentModificationException if it is detected that the remapping function
     * modified this map
     */
    public V computeIfPresent
        (K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        return super.computeIfPresent(key, remappingFunction);
    }

    /**
     * Attempts to compute a mapping for the specified key and its current mapped value (or null if
     * there is no current mapping). For example, to either create or append a String msg to a
     * value mapping:
     * 
     * <BR ><DIV CLASS=SNIP>{@code
     * map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))
     * }</DIV>
     * 
     * <BR /><BR />(Method merge() is often simpler to use for such purposes.)
     * 
     * <BR /><BR />If the remapping function returns null, the mapping is removed (or remains
     * absent if initially absent). If the remapping function itself throws an (unchecked)
     * exception, the exception is rethrown, and the current mapping is left unchanged.
     * 
     * <BR /><BR />The remapping function should not modify this map during computation.
     * 
     * <BR /><BR />This method will, on a best-effort basis, throw a
     * {@link ConcurrentModificationException} if it is detected that the remapping function
     * modifies this map during computation.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param key key with which the specified value is to be associated
     * @param remappingFunction the remapping function to compute a value
     * @return the new value associated with the specified key, or null if none
     *
     * @throws ConcurrentModificationException if it is detected that the remapping function
     * modified this map
     */
    public V compute(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        return super.compute(key, remappingFunction);
    }

    /**
     * If the specified key is not already associated with a value or is associated with null,
     * associates it with the given non-null value. Otherwise, replaces the associated value with
     * the results of the given remapping function, or removes if the result is null. This method
     * may be of use when combining multiple mapped values for a key. For example, to either create
     * or append a String msg to a value mapping:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * map.merge(key, msg, String::concat)
     * }</DIV>
     * 
     * <BR /><BR />If the remapping function returns null, the mapping is removed. If the remapping
     * function itself throws an (unchecked) exception, the exception is rethrown, and the current
     * mapping is left unchanged.
     * 
     * <BR /><BR />The remapping function should not modify this map during computation.
     * 
     * <BR /><BR />This method will, on a best-effort basis, throw a
     * {@code ConcurrentModificationException} if it is detected that the remapping function
     * modifies this map during computation.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param key key with which the resulting value is to be associated
     * 
     * @param value the non-null value to be merged with the existing value associated with the key
     * or, if no existing value or a null value is associated with the key, to be associated with
     * the key
     * 
     * @parma remappingFunction the remapping function to recompute a value if present
     * 
     * @return the new value associated with the specified key, or null if no value is associated
     * with the key
     * 
     * @throws ConcurrentModificationException if it is detected that the remapping function
     * modified this map
     */
    public V merge(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        return super.merge(key, value, remappingFunction);
    }

    /**
     * Replaces each entry's value with the result of invoking the given function on that entry
     * until all entries have been processed or the function throws an exception. Exceptions thrown
     * by the function are relayed to the caller.
     * 
     * <BR /><BR />The implementation is equivalent to:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * for (Map.Entry<K, V> entry : map.entrySet())
     *      entry.setValue(function.apply(entry.getKey(), entry.getValue()));
     * }</DIV>
     * 
     * <BR /><BR />No guarantees about synchronization or atomicity properties of this method.
     * 
     * <EMBED DATA-TYPE=HashMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param function the function to apply to each entry
     * 
     * @throws UnsupportedOperationException if the set operation is not supported by this map's
     * entry set iterator.
     * 
     * @throws ClassCastException if the class of a replacement value prevents it from being
     * stored in this map (optional)
     * 
     * @throws NullPointerException if the specified function is null, or if a replacement value is
     * null and this map does not permit null values (optional)
     * 
     * @throws IllegalArgumentException if some property of a replacement value prevents it from
     * being stored in this map (optional)
     * 
     * @throws ConcurrentModificationException - if an entry is found to be removed during
     * iteration
     */
    public void replaceAll(BiFunction<? super K, ? super V, ? extends V> function)
    {
        if (this.built) throw new AttemptedModificationException(ROHM);
        super.replaceAll(function);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Methods inherited from class java.util.HashMap
    // ********************************************************************************************
    // ********************************************************************************************


    // containsKey, containsValue, entrySet, forEach, get, getOrDefault, isEmpty, keySet, size,
    // values
    //
    // Introspection Only:  containsKey, containsValue, forEach, get, getOrDefault, isEmpty, size
    // Mutator or Potential Mutator: entrySet, keySet, values
    //
    // *** OTHER INHERITED METHODS - ALL READ-ONLY METHODS ***
    //
    // Methods inherited from class java.util.AbstractMap: hashCode, toString
    // Methods inherited from interface java.util.Map: hashCode

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=Set DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.Set} that cannot modify this {@code HashMap-Builder}
     */
    public Set<Map.Entry<K, V>> entrySet()
    { return Collections.unmodifiableSet(super.entrySet()); }

    Set<Map.Entry<K, V>> _entrySet(ReadOnlyHashMap.AccessBadge friendClassBadge)
    { return super.entrySet(); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=Set DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.Set} that cannot modify this {@code HashMap-Builder}
     */
    public Set<K> keySet()
    { return Collections.unmodifiableSet(super.keySet()); }

    Set<K> _keySet(ReadOnlyHashMap.AccessBadge friendClassBadge)
    { return super.keySet(); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=Collection DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.Collection} that cannot modify this {@code HashMap-Builder}
     */
    public Collection<V> values()
    { return Collections.unmodifiableCollection(super.values()); }

    Collection<V> _values(ReadOnlyHashMap.AccessBadge friendClassBadge)
    { return super.values(); }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object & Cloneable
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Compares the specified Object with this Builder for equality, as per the definition in the
     * original class {@code java.util.HashMap}.  Ignores the private field {@code 'built'}.  If
     * {@code 'this'} has not been built, but {@code 'o'} has been, that fact is ignored during the
     * equality-comparison.
     *
     * @param  o object to be compared for equality with this {@code ROHashMapBuilder} instance
     * @return true if the specified Object is equal to this Builder
     */
    public synchronized boolean equals(Object o)
    {
        if (this == o) return true;
        if (! (o instanceof ROHashMapBuilder)) return false;
        return super.equals((HashMap) o);
    }

    /**
     * Clones this instance' of {@code ROHashMapBuilder}.
     * 
     * <BR /><BR />The clone that's returned has had it's internal {@code 'built'} boolean-flag set
     * {@code FALSE}
     * 
     * @return a clone of this builder
     */
    public synchronized ROHashMapBuilder<K, V> clone()
    { return new ROHashMapBuilder<>(this); }

    private ROHashMapBuilder(ROHashMapBuilder<K, V> rohmb)
    { super(rohmb); this.built=false; }
}