/*
 * Copyright (c) 1997, 2018, 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.BiFunction;
import java.util.function.Function;

import java.util.*;

/**
 * A Copy of Java's {@code TreeMap} class; used for building a {@link ReadOnlyTreeMap}.
 * Maintains <I>an internal and inaccessible {@code TreeMap<E>} instance</I>.  
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=TreeMap>
 * <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 ReadOnlyTreeMap
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_BUILDER")
public final class ROTreeMapBuilder<K, V>
    extends TreeMap<K, V>
    implements Cloneable, Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Fields & Builder
    // ********************************************************************************************
    // ********************************************************************************************


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

    // Exception messages need this
    private static final String ROTM = "TreeMap";

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

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


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


    /**
     * Constructs a new, empty {@code ROTreeMapBuilder} (tree map), using the natural ordering of
     * its keys.  All keys inserted into the map must implement the {@link Comparable} interface.
     * Furthermore, all such keys must be <em>mutually comparable</em>: {@code k1.compareTo(k2)}
     * must not throw a {@code ClassCastException} for any keys {@code k1} and {@code k2} in the
     * map.  If the user attempts to put a key into the map that violates this constraint (for
     * example, the user attempts to put a string key into a map whose keys are integers), the
     * {@code put(Object key, Object value)} call will throw a {@code ClassCastException}.
     */
    public ROTreeMapBuilder()
    { super(); }

    /**
     * Constructs a new, empty {@code ROTreeMapBuilder} (tree map), ordered according to the given
     * comparator.  All keys inserted into the map must be <em>mutually comparable</em> by the
     * given comparator: {@code comparator.compare(k1, k2)} must not throw a
     * {@code ClassCastException} for any keys {@code k1} and {@code k2} in the map.  If the user
     * attempts to put a key into the map that violates this constraint, the {@code put(Object key,
     * Object value)} call will throw a {@code ClassCastException}.
     *
     * @param comparator the comparator that will be used to order this map.  If {@code null}, the
     * {@linkplain Comparable natural ordering} of the keys will be used.
     */
    public ROTreeMapBuilder(Comparator<? super K> comparator)
    { super(comparator); }

    /**
     * Constructs a new {@code ROTreeMapBuilder} (tree map) containing the same mappings as the
     * given map, ordered according to the <em>natural ordering</em> of its keys.  All keys
     * inserted into the new map must implement the {@link Comparable} interface.  Furthermore, all
     * such keys must be <em>mutually comparable</em>: {@code k1.compareTo(k2)} must not throw a
     * {@code ClassCastException} for any keys {@code k1} and {@code k2} in the map.  This method
     * runs in n*log(n) time.
     *
     * @param  m the map whose mappings are to be placed in this map
     * 
     * @throws ClassCastException if the keys in m are not {@link Comparable}, or are not mutually
     * comparable
     * 
     * @throws NullPointerException if the specified map is null
     */
    public ROTreeMapBuilder(Map<? extends K, ? extends V> m)
    { super(m); }

    /**
     * Constructs a new {@code ROTreeMapBuilder} (tree map) containing the same mappings and using
     * the same ordering as the specified sorted map.  This method runs in linear time.
     *
     * @param  m the sorted map whose mappings are to be placed in this map, and whose comparator
     * is to be used to sort this map
     * 
     * @throws NullPointerException if the specified map is null
     */
    public ROTreeMapBuilder(SortedMap<K, ? extends V> m)
    { super(m); }


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


    /**
     * Copies all of the mappings from the specified map to this map.  These mappings replace any
     * mappings that this map had for any of the keys currently in the specified map.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param  map mappings to be stored in this map
     * 
     * @throws ClassCastException if the class of a key or value in the specified map prevents it
     * from being stored in this map
     * 
     * @throws NullPointerException if the specified map is null or the specified map contains a
     * null key and this map does not permit null keys
     */
    public void putAll(Map<? extends K, ? extends V> map)
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        super.putAll(map); 
    }

    /**
     * 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=TreeMap 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}.)
     * 
     * @throws ClassCastException if the specified key cannot be compared with the keys currently
     * in the map
     *
     * @throws NullPointerException if the specified key is null and this map uses natural
     * ordering, or its comparator does not permit null keys
     */
    public V put(K key, V value)
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        return super.put(key, value); 
    }

    /**
     * Removes the mapping for this key from this TreeMap if present.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param  key key for which mapping should be removed
     * 
     * @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}.)
     * 
     * @throws ClassCastException if the specified key cannot be compared with the keys currently
     * in the map
     * 
     * @throws NullPointerException if the specified key is null and this map uses natural
     * ordering, or its comparator does not permit null keys
     */
    public V remove(Object key)
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        return super.remove(key); 
    }

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

    /**
     * Removes and returns a key-value mapping associated with the least key in this map, or null
     * if the map is empty.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @return the removed first entry of this map, or null if this map is empty
     */
    public Map.Entry<K,V> pollFirstEntry()
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        return super.pollFirstEntry(); 
    }

    /**
     * Removes and returns a key-value mapping associated with the greatest key in this map, or
     * null if the map is empty.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @return the removed last entry of this map, or null if this map is empty
     */
    public Map.Entry<K,V> pollLastEntry()
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        return super.pollLastEntry(); 
    }

    /**
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 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;
     * }
     * 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.  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.
     * 
     * @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 newValue is null, and this map does not
     * permit null keys or values.  If oldValue is null and this map does not permit null values
     * (optional)
     * 
     * @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(ROTM);
        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:
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * return map.containsKey(key)
     *      ? map.put(key, value);
     *      : null;
     * }</DIV>
     * 
     * <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=TreeMap 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 (optional)
     * 
     * @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(ROTM);
        return super.replace(key, value); 
    }

    /**
     * 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 default implementation is equivalent to, for this map:
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * for (Map.Entry<K, V> entry : map.entrySet())
     *      entry.setValue(function.apply(entry.getKey(), entry.getValue()));
     * }</DIV>
     * 
     * <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=TreeMap 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 (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(ROTM);
        super.replaceAll(function); 
    }


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


    // ceilingEntry, ceilingKey, comparator, containsKey, containsValue, descendingKeySet,
    // descendingMap, entrySet, firstEntry, firstKey, floorEntry, floorKey, forEach, get, headMap,
    // headMap, higherEntry, higherKey, keySet, lastEntry, lastKey, lowerEntry, lowerKey,
    // navigableKeySet, size, subMap, subMap, tailMap, tailMap, values
    // 
    // Introspection Only: ceilingEntry, ceilingKey, comparator, containsKey, containsValue,
    //                     firstEntry, firstKey, floorEntry, floorKey, forEach, get, higherEntry,
    //                     higherKey, lastEntry, lastKey, lowerEntry, lowerKey, size
    // 
    // Potential-Mutator: descendingKeySet, descendingMap, entrySet, headMap, headMap, keySet,
    //                    navigableKeySet, subMap, subMap, tailMap, tailMap, values
    //
    // Methods declared in interface java.util.Map
    // compute, computeIfAbsent, computeIfPresent, getOrDefault, hashCode, isEmpty, merge,
    // putIfAbsent, remove

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

    // *** Java-HTML: 
    // Looking at the JDK-21 Code for TreeMap, descendingKeySet() just calls the stuff lited below
    // This supbstitution has to happen, or else the AccessDeniedException throws

    NavigableSet<K> _descendingKeySet(ReadOnlyTreeMap.AccessBadge friendClassBadge)
    { return super.descendingMap().navigableKeySet(); /* descendingKeySet(); */}

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

    NavigableMap<K,V> _descendingMap(ReadOnlyTreeMap.AccessBadge friendClassBadge)
    { return super.descendingMap(); }

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

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

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html' DATA-RET_TYPE=SortedMap DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.SortedMap} that cannot modify this {@code TreeMap-Builder}
     */
    public SortedMap<K,V> headMap(K toKey)
    { return Collections.unmodifiableSortedMap(super.headMap(toKey, false));  }

    // *** Java-HTML: 
    // Looking at the JDK-21 Code for TreeMap, headMap(K) just calls headMap(K, boolean)
    // This supbstitution has to happen, or else the AccessDeniedException throws

    SortedMap<K,V> _headMap(K toKey, ReadOnlyTreeMap.AccessBadge friendClassBadge)
    { return super.headMap(toKey, false); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html' DATA-RET_TYPE=NavigableMap DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.NavigableMap} that cannot modify this {@code TreeMap-Builder}
     */
    public NavigableMap<K,V> headMap(K toKey, boolean inclusive)
    { return Collections.unmodifiableNavigableMap(super.headMap(toKey, inclusive)); }

    NavigableMap<K,V> _headMap
        (K toKey, boolean inclusive, ReadOnlyTreeMap.AccessBadge friendClassBadge)
    { return super.headMap(toKey, inclusive); }

    /**
     * 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 TreeMap-Builder}
     */
    public Set<K> keySet()
    { return Collections.unmodifiableSet(super.navigableKeySet()); }

    // *** Java-HTML: 
    // Looking at the JDK-21 Code for TreeMap, keySet() just calls navigableKeySet()
    // This supbstitution has to happen, or else the AccessDeniedException throws

    Set<K> _keySet(ReadOnlyTreeMap.AccessBadge friendClassBadge)
    { return /* *** Java-HTML: super.keySet(); */ super.navigableKeySet(); }

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

    NavigableSet<K> _navigableKeySet(ReadOnlyTreeMap.AccessBadge friendClassBadge)
    { return super.navigableKeySet(); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html' DATA-RET_TYPE=NavigableMap DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.NavigableMap} that cannot modify this {@code TreeMap-Builder}
     */
    public NavigableMap<K,V> subMap
        (K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)
    {
        return Collections.unmodifiableNavigableMap
            (super.subMap(fromKey, fromInclusive, toKey, toInclusive));
    }

    NavigableMap<K,V> _subMap(
            K fromKey, boolean fromInclusive, K toKey, boolean toInclusive,
            ReadOnlyTreeMap.AccessBadge friendClassBadge
        )
    { return super.subMap(fromKey, fromInclusive, toKey, toInclusive); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html' DATA-RET_TYPE=SortedMap DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.SortedMap} that cannot modify this {@code TreeMap-Builder}
     */
    public SortedMap<K,V> subMap(K fromKey, K toKey)
    { return Collections.unmodifiableSortedMap(super.subMap(fromKey, true, toKey, false));  }

    // *** Java-HTML: 
    // Looking at the JDK-21 Code for TreeMap, subMap(K, K) invokes subMap(K, boolean, K, boolean)
    // This supbstitution has to happen, or else the AccessDeniedException throws

    SortedMap<K,V> _subMap(K fromKey, K toKey, ReadOnlyTreeMap.AccessBadge friendClassBadge)
    { return super.subMap(fromKey, true, toKey, false); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html' DATA-RET_TYPE=SortedMap DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.SortedMap} that cannot modify this {@code TreeMap-Builder}
     */
    public SortedMap<K,V> tailMap(K fromKey)
    { return Collections.unmodifiableSortedMap(super.tailMap(fromKey, true));  }

    // *** Java-HTML: 
    // Looking at the JDK-21 Code for TreeMap, tailMap(K) just calls tailMap(K, boolean)
    // This supbstitution has to happen, or else the AccessDeniedException throws

    SortedMap<K,V> _tailMap(K fromKey, ReadOnlyTreeMap.AccessBadge friendClassBadge)
    { return super.tailMap(fromKey, true); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html' DATA-RET_TYPE=NavigableMap DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.NavigableMap} that cannot modify this {@code TreeMap-Builder}
     */
    public NavigableMap<K,V> tailMap(K fromKey, boolean inclusive)
    { return Collections.unmodifiableNavigableMap(super.tailMap(fromKey, inclusive)); }

    NavigableMap<K,V> _tailMap
        (K fromKey, boolean inclusive, ReadOnlyTreeMap.AccessBadge friendClassBadge)
    { return super.tailMap(fromKey, inclusive); }

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

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


    // ********************************************************************************************
    // ********************************************************************************************
    // Methods declared in interface java.util.Map 
    // ********************************************************************************************
    // ********************************************************************************************

    // RE-COPIED FROM ABOVE
    // compute, computeIfAbsent, computeIfPresent, getOrDefault, hashCode, isEmpty, merge,
    // putIfAbsent, remove
    //
    // Introspection Methods: getOrDefault, hashCode, isEmpty
    // Mutator Methods: compute, computeIfAbsent, computeIfPresent, merge, putIfAbsent, remove

    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
    public V compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        return super.compute(key, remappingFunction);
    }

    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
    public V computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        return super.computeIfAbsent(key, mappingFunction);
    }

    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
    public V computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        return super.computeIfPresent(key, remappingFunction);
    }

    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
    public V merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        return super.merge(key, value, remappingFunction);
    }

    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
    public  V putIfAbsent(K key, V value)
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        return super.putIfAbsent(key, value);
    }

    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
    public boolean remove(Object key, Object value)
    {
        if (this.built) throw new AttemptedModificationException(ROTM);
        return super.remove(key, value);
    }


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


    /**
     * Compares the specified Object with this Builder for equality, as per the definition in the
     * private and internal field {@code 'treeMap'}.
     *
     * @param  o object to be compared for equality with this {@code ROTreeMapBuilder} instance
     * @return true if the specified Object is equal to this Builder
     */
    public boolean equals(Object o)
    {
        if (this == o) return true;
        if (! (o instanceof ROTreeMapBuilder)) return false;
        return super.equals((TreeMap) o);
    }

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

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