/*
 * 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.Function;
import java.util.function.BiFunction;

/**
 * A Copy of Java's {@code Hashtable} class; used for building a {@link ReadOnlyHashtable}.
 * Maintains <I>an internal and inaccessible {@code Hashtable<K, V>} instance</I>. 
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=Hashtable>
 * <EMBED CLASS='external-html' DATA-A_AN=a DATA-FILE-ID=BUILDERS>
 * <EMBED CLASS='external-html' DATA-FILE-ID=SYNCHRONIZED>
 * 
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 * @see ReadOnlyHashtable
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_BUILDER")
public final class ROHashtableBuilder<K, V>
    extends Hashtable<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 ROHT = "Hashtable";

    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 Hashtable} to the 
     * {@code ReadOnlyHashtable} Wrapper-Class.
     * 
     * @return a newly constructed {@code ReadOnlyHashtable} "Wrapper-Class", shielding the
     * internal {@code 'hashTable'} private-field from any modification.
     */
    public synchronized ReadOnlyHashtable<K, V> build()
    {
        this.built = true;

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


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


    /**
     * Constructs a new, empty {@code ROHashtableBuilder} with the specified initial capacity and
     * the specified load factor.
     *
     * @param initialCapacity the initial capacity of the hashtable.
     * @param loadFactor the load factor of the hashtable.
     * 
     * @throws IllegalArgumentException  if the initial capacity is les than zero, or if the load
     * factor is nonpositive.
     */
    public ROHashtableBuilder(int initialCapacity, float loadFactor)
    { super(initialCapacity, loadFactor); }

    /**
     * Constructs a new, empty {@code ROHashtableBuilder} with the specified initial capacity and
     * default load factor (0.75).
     *
     * @param initialCapacity   the initial capacity of the hashtable.
     * @throws IllegalArgumentException if the initial capacity is less than zero.
     */
    public ROHashtableBuilder(int initialCapacity)
    { super(initialCapacity); }

    /**
     * Constructs a new, empty {@code ROHashtableBuilder} with a default initial capacity (11) and
     * load factor (0.75).
     */
    public ROHashtableBuilder()
    { this(11, 0.75f); }

    /**
     * Constructs a new {@code ROHashtableBuilder} with the same mappings as the given Map.  The
     * builder is created with an initial capacity sufficient to hold the mappings in the given Map
     * and a default load factor (0.75).
     *
     * @param t the map whose mappings are to be placed in this map.
     * @throws NullPointerException if the specified map is null.
     */
    public ROHashtableBuilder(Map<? extends K, ? extends V> t)
    {
        // Note that below is the actual Hashtable Constructor Code.  It **DOES NOT** break the
        // "Read Only Contract" - Specifically, subsequent changes to 't' **WILL NOT** write
        // through into this internal hashTable instance.  They are copied / cloned "into" this map

        super(t);
    }


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



    /**
     * Maps the specified {@code key} to the specified {@code value} in this hashtable. Neither the
     * key nor the value can be {@code null}.
     *
     * <BR /><BR />The value can be retrieved by calling the {@code get} method with a key that is
     * equal to the original key.
     * 
     * <EMBED DATA-TYPE=Hashtable CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param key the hashtable key
     * @param value the value
     * 
     * @return the previous value of the specified key in this hashtable, or {@code null} if it did
     * not have one
     * 
     * @throws NullPointerException  if the key or value is {@code null}
     * @see #get(Object)
     */
    public synchronized V put(K key, V value)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        return super.put(key, value); 
    }

    /**
     * Removes the key (and its corresponding value) from this hashtable. This method does nothing
     * if the key is not in the hashtable.
     * 
     * <EMBED DATA-TYPE=Hashtable CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param key the key that needs to be removed
     * 
     * @return the value to which the key had been mapped in this hashtable, or {@code null} if the
     * key did not have a mapping
     * 
     * @throws NullPointerException if the key is {@code null}
     */
    public synchronized V remove(Object key)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        return super.remove(key); 
    }

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

    /**
     * Clears this hashtable so that it contains no keys.
     * <EMBED DATA-TYPE=Hashtable CLASS='external-html' DATA-FILE-ID=MUTATOR>
     */
    public synchronized void clear()
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        super.clear(); 
    }


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



    /**
     * 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.
     * 
     * The default implementation is equivalent to, for this map:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * for (Map.Entry<K, V> entry : map.entrySet())
     *      entry.setValue(function.apply(entry.getKey(), entry.getValue()));
     * }</DIV>
     * 
     * <EMBED DATA-TYPE=Hashtable CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param function the function to apply to each entry
     * 
     * @throws ClassCastException if the class of a replacement value prevents it from being stored
     * in this map
     * 
     * @throws NullPointerException if the specified function or the replacement value is null
     * @throws ConcurrentModificationException - if an entry is found to be removed during iteration
     */
    public synchronized void replaceAll(BiFunction<? super K, ? super V, ? extends V> function)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        super.replaceAll(function); 
    }

    /**
     * If the specified key is not already associated with a value (or is mapped to null)
     * associates it with the given value and returns null, else returns the current value.
     * 
     * <BR /><BR />The default implementation is equivalent to, for this map:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * V v = map.get(key);
     * if (v == null) v = map.put(key, value);
     * return v;
     * }</DIV>
     * 
     * <EMBED DATA-TYPE=Hashtable 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 null if there was no
     * mapping for the key. (A null return can also indicate that the map previously associated
     * null with the key, if the implementation supports null values.)
     * 
     * @throws ClassCastException if the key or value is of an inappropriate type for this map
     * (optional)
     * 
     * @throws NullPointerException if the specified key or value is null
     */
    public synchronized V putIfAbsent(K key, V value)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        return super.putIfAbsent(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 map:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * if (map.containsKey(key) && Objects.equals(map.get(key), oldValue))
     * {
     *      map.put(key, newValue);
     *      return true;
     * }
     * 
     * else return false;
     * }</DIV>
     * 
     * <EMBED DATA-TYPE=Hashtable 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 replaced
     * 
     * @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
     */
    public synchronized boolean remove(Object key, Object value)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        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 map:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * if (map.containsKey(key) && Objects.equals(map.get(key), oldValue))
     * {
     *      map.put(key, newValue);
     *      return true;
     * }
     * 
     * else return false;
     * }</DIV>
     * 
     * <BR /><BR />The default implementation does not throw NullPointerException for maps that do
     * not support null values if oldValue is null unless newValue is also null.
     * 
     * <EMBED DATA-TYPE=Hashtable 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 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 oldValue / newValue is null
     */
    public synchronized boolean replace(K key, V oldValue, V newValue)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        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 map:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * if (map.containsKey(key))    return map.put(key, value);
     * else                         return null;
     * }</DIV>
     * 
     * <EMBED DATA-TYPE=Hashtable 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 null if there was no
     * mapping for the key. (A null return can also indicate that the map previously associated
     * null with the key, if the implementation supports null values.)
     * 
     * @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
     */
    public synchronized V replace(K key, V value)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        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 />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 java.util.ConcurrentModificationException} if the mapping function modified this map
     * during computation.
     * 
     * <EMBED DATA-TYPE=Hashtable 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 synchronized V computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        return 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.  If the remapping function returns null,
     * the mapping is removed.
     * 
     * <BR /><BR />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 java.util.ConcurrentModificationException} if the remapping function modified this
     * map during computation.
     * 
     * <EMBED DATA-TYPE=Hashtable 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 synchronized V computeIfPresent
       (K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        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
     * {@code ConcurrentModificationException} if the remapping function modified this map during
     * computation.
     * 
     * <BR /><BR />This method will, on a best-effort basis, throw a
     * {@link java.util.ConcurrentModificationException} if the remapping function modified this
     * map during computation.
     * 
     * <EMBED DATA-TYPE=Hashtable 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 synchronized V compute
        (K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        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 />This method will, on a best-effort basis, throw a
     * {@code java.util.ConcurrentModificationException} if the remapping function modified this
     * map during computation.
     * 
     * <EMBED DATA-TYPE=Hashtable 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
     * 
     * @param 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 synchronized V merge
        (K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROHT);
        return super.merge(key, value, remappingFunction); 
    }


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


    // contains, containsKey, containsValue, elements, entrySet, forEach, get, getOrDefault,
    // hashCode, isEmpty, keys, keySet, rehash, size, toString, values
    // 
    // Introspection Only:  contains, containsKey, containsValue, elements, forEach, get,
    //                      getOrDefault, hashCode, isEmpty, keys, size, toString
    //
    // Potential Mutator: entrySet, keySet, values

    /**
     * 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 Hashtable-Builder}
     */
    public Set<Map.Entry<K, V>> entrySet()
    { return Collections.unmodifiableSet(super.entrySet()); }

    Set<Map.Entry<K, V>> _entrySet(ReadOnlyHashtable.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 Hashtable-Builder}
     */
    public Set<K> keySet()
    { return Collections.unmodifiableSet(super.keySet()); }

    Set<K> _keySet(ReadOnlyHashtable.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 Hashtable-Builder}
     */
    public Collection<V> values()
    { return Collections.unmodifiableCollection(super.values()); }

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


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


    /**
     * Compares the specified Object with this Builder for equality, as per the definition in the
     * private and internal field {@code 'hashTable'}.
     *
     * @param  o object to be compared for equality with this {@code ROHashtableBuilder} 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 ROHashtableBuilder)) return false;
        return super.equals((Hashtable) o);
    }

    /**
     * Clones this instance' of {@code ROHashtableBuilder}.
     * 
     * <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 ROHashtableBuilder<K, V> clone()
    { return new ROHashtableBuilder<>(this); }

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