Source code

001/*
002 * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025package Torello.Java.ReadOnly;
026
027import java.io.Serializable;
028
029import java.util.function.BiFunction;
030import java.util.function.Function;
031
032import java.util.*;
033
034/**
035 * A Copy of Java's {@code TreeMap} class; used for building a {@link ReadOnlyTreeMap}.
036 * Maintains <I>an internal and inaccessible {@code TreeMap<E>} instance</I>.  
037 * 
038 * <EMBED CLASS=globalDefs DATA-JDK=TreeMap>
039 * <EMBED CLASS='external-html' DATA-A_AN=a DATA-FILE-ID=BUILDERS>
040 * 
041 * @param <K> the type of keys maintained by this map
042 * @param <V> the type of mapped values
043 * @see ReadOnlyTreeMap
044 */
045@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_BUILDER")
046public final class ROTreeMapBuilder<K, V>
047    extends TreeMap<K, V>
048    implements Cloneable, Serializable
049{
050    // ********************************************************************************************
051    // ********************************************************************************************
052    // Fields & Builder
053    // ********************************************************************************************
054    // ********************************************************************************************
055
056
057    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
058    protected static final long serialVersionUID = 1;
059
060    // Exception messages need this
061    private static final String ROTM = "TreeMap";
062
063    private boolean built = false;
064
065    // Mimics the C++ Concept of "Friend Class".  This badge is utilized by the "build()" method
066    // directly below this inner-class declaration.  It is the only place where this declaration is
067    // actually used anywhere.  This prohibits access to the constructor that is used to anybody
068    // else
069
070    static class AccessBadge { private AccessBadge() { } }
071    private static final AccessBadge friendClassBadge = new AccessBadge();
072
073    /**
074     * Simply transfers {@code 'this'} instance' internal {@code TreeMap} to the 
075     * {@code ReadOnlyTreeMap} Wrapper-Class.
076     * 
077     * @return a newly constructed {@code ReadOnlyTreeMap} "Wrapper-Class", shielding the
078     * internal {@code 'treeMap'} private-field from any modification.
079     */
080    public ReadOnlyTreeMap<K, V> build()
081    {
082        this.built = true;
083
084        return (size() == 0)
085            ? ReadOnlyTreeMap.emptyROTM()
086            : new ReadOnlyTreeMap<>(this, friendClassBadge);
087    }
088
089
090    // ********************************************************************************************
091    // ********************************************************************************************
092    // Modified Constructors
093    // ********************************************************************************************
094    // ********************************************************************************************
095
096
097    /**
098     * Constructs a new, empty {@code ROTreeMapBuilder} (tree map), using the natural ordering of
099     * its keys.  All keys inserted into the map must implement the {@link Comparable} interface.
100     * Furthermore, all such keys must be <em>mutually comparable</em>: {@code k1.compareTo(k2)}
101     * must not throw a {@code ClassCastException} for any keys {@code k1} and {@code k2} in the
102     * map.  If the user attempts to put a key into the map that violates this constraint (for
103     * example, the user attempts to put a string key into a map whose keys are integers), the
104     * {@code put(Object key, Object value)} call will throw a {@code ClassCastException}.
105     */
106    public ROTreeMapBuilder()
107    { super(); }
108
109    /**
110     * Constructs a new, empty {@code ROTreeMapBuilder} (tree map), ordered according to the given
111     * comparator.  All keys inserted into the map must be <em>mutually comparable</em> by the
112     * given comparator: {@code comparator.compare(k1, k2)} must not throw a
113     * {@code ClassCastException} for any keys {@code k1} and {@code k2} in the map.  If the user
114     * attempts to put a key into the map that violates this constraint, the {@code put(Object key,
115     * Object value)} call will throw a {@code ClassCastException}.
116     *
117     * @param comparator the comparator that will be used to order this map.  If {@code null}, the
118     * {@linkplain Comparable natural ordering} of the keys will be used.
119     */
120    public ROTreeMapBuilder(Comparator<? super K> comparator)
121    { super(comparator); }
122
123    /**
124     * Constructs a new {@code ROTreeMapBuilder} (tree map) containing the same mappings as the
125     * given map, ordered according to the <em>natural ordering</em> of its keys.  All keys
126     * inserted into the new map must implement the {@link Comparable} interface.  Furthermore, all
127     * such keys must be <em>mutually comparable</em>: {@code k1.compareTo(k2)} must not throw a
128     * {@code ClassCastException} for any keys {@code k1} and {@code k2} in the map.  This method
129     * runs in n*log(n) time.
130     *
131     * @param  m the map whose mappings are to be placed in this map
132     * 
133     * @throws ClassCastException if the keys in m are not {@link Comparable}, or are not mutually
134     * comparable
135     * 
136     * @throws NullPointerException if the specified map is null
137     */
138    public ROTreeMapBuilder(Map<? extends K, ? extends V> m)
139    { super(m); }
140
141    /**
142     * Constructs a new {@code ROTreeMapBuilder} (tree map) containing the same mappings and using
143     * the same ordering as the specified sorted map.  This method runs in linear time.
144     *
145     * @param  m the sorted map whose mappings are to be placed in this map, and whose comparator
146     * is to be used to sort this map
147     * 
148     * @throws NullPointerException if the specified map is null
149     */
150    public ROTreeMapBuilder(SortedMap<K, ? extends V> m)
151    { super(m); }
152
153
154    // ********************************************************************************************
155    // ********************************************************************************************
156    // Original JDK Methods
157    // ********************************************************************************************
158    // ********************************************************************************************
159
160
161    /**
162     * Copies all of the mappings from the specified map to this map.  These mappings replace any
163     * mappings that this map had for any of the keys currently in the specified map.
164     * 
165     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
166     *
167     * @param  map mappings to be stored in this map
168     * 
169     * @throws ClassCastException if the class of a key or value in the specified map prevents it
170     * from being stored in this map
171     * 
172     * @throws NullPointerException if the specified map is null or the specified map contains a
173     * null key and this map does not permit null keys
174     */
175    public void putAll(Map<? extends K, ? extends V> map)
176    {
177        if (this.built) throw new AttemptedModificationException(ROTM);
178        super.putAll(map); 
179    }
180
181    /**
182     * Associates the specified value with the specified key in this map. If the map previously
183     * contained a mapping for the key, the old value is replaced.
184     * 
185     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
186     *
187     * @param key key with which the specified value is to be associated
188     * @param value value to be associated with the specified key
189     *
190     * @return the previous value associated with {@code key}, or {@code null} if there was no
191     * mapping for {@code key}.  (A {@code null} return can also indicate that the map previously
192     * associated {@code null} with {@code key}.)
193     * 
194     * @throws ClassCastException if the specified key cannot be compared with the keys currently
195     * in the map
196     *
197     * @throws NullPointerException if the specified key is null and this map uses natural
198     * ordering, or its comparator does not permit null keys
199     */
200    public V put(K key, V value)
201    {
202        if (this.built) throw new AttemptedModificationException(ROTM);
203        return super.put(key, value); 
204    }
205
206    /**
207     * Removes the mapping for this key from this TreeMap if present.
208     * 
209     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
210     *
211     * @param  key key for which mapping should be removed
212     * 
213     * @return the previous value associated with {@code key}, or {@code null} if there was no
214     * mapping for {@code key}.  (A {@code null} return can also indicate that the map previously
215     * associated {@code null} with {@code key}.)
216     * 
217     * @throws ClassCastException if the specified key cannot be compared with the keys currently
218     * in the map
219     * 
220     * @throws NullPointerException if the specified key is null and this map uses natural
221     * ordering, or its comparator does not permit null keys
222     */
223    public V remove(Object key)
224    {
225        if (this.built) throw new AttemptedModificationException(ROTM);
226        return super.remove(key); 
227    }
228
229    /**
230     * Removes all of the mappings from this map.  The map will be empty after this call returns.
231     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
232     */
233    public void clear()
234    {
235        if (this.built) throw new AttemptedModificationException(ROTM);
236        super.clear(); 
237    }
238
239    /**
240     * Removes and returns a key-value mapping associated with the least key in this map, or null
241     * if the map is empty.
242     * 
243     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
244     * 
245     * @return the removed first entry of this map, or null if this map is empty
246     */
247    public Map.Entry<K,V> pollFirstEntry()
248    {
249        if (this.built) throw new AttemptedModificationException(ROTM);
250        return super.pollFirstEntry(); 
251    }
252
253    /**
254     * Removes and returns a key-value mapping associated with the greatest key in this map, or
255     * null if the map is empty.
256     * 
257     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
258     * 
259     * @return the removed last entry of this map, or null if this map is empty
260     */
261    public Map.Entry<K,V> pollLastEntry()
262    {
263        if (this.built) throw new AttemptedModificationException(ROTM);
264        return super.pollLastEntry(); 
265    }
266
267    /**
268     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
269     * Replaces the entry for the specified key only if currently mapped to the specified value.
270     * 
271     * <BR /><BR />The default implementation is equivalent to, for this map:
272     * 
273     * <BR /><DIV CLASS=SNIP>{@code
274     * if (map.containsKey(key) && Objects.equals(map.get(key), oldValue))
275     * {
276     *     map.put(key, newValue);
277     *     return true;
278     * }
279     * return false;
280     * }</DIV>
281     * 
282     * <BR /><BR />The default implementation does not throw NullPointerException for maps that do 
283     * not support null values if oldValue is null unless newValue is also null.  The default
284     * implementation makes no guarantees about synchronization or atomicity properties of this
285     * method. Any implementation providing atomicity guarantees must override this method and
286     * document its concurrency properties.
287     * 
288     * @param key key with which the specified value is associated
289     * @param oldValue value expected to be associated with the specified key
290     * @param newValue value to be associated with the specified key
291     * @return {@code TRUE} if the value was replaced
292     * 
293     * @throws ClassCastException if the class of a specified key or value prevents it from being
294     * stored in this map
295     * 
296     * @throws NullPointerException if a specified key or newValue is null, and this map does not
297     * permit null keys or values.  If oldValue is null and this map does not permit null values
298     * (optional)
299     * 
300     * @throws IllegalArgumentException if some property of a specified key or value prevents it
301     * from being stored in this map
302     */
303    public boolean replace(K key, V oldValue, V newValue)
304    {
305        if (this.built) throw new AttemptedModificationException(ROTM);
306        return super.replace(key, oldValue, newValue); 
307    }
308
309    /**
310     * Replaces the entry for the specified key only if it is currently mapped to some value.
311     * 
312     * <BR /><BR />The default implementation is equivalent to, for this map:
313     * 
314     * <DIV CLASS=EXAMPLE>{@code
315     * return map.containsKey(key)
316     *      ? map.put(key, value);
317     *      : null;
318     * }</DIV>
319     * 
320     * <BR />The default implementation makes no guarantees about synchronization or atomicity
321     * properties of this method. Any implementation providing atomicity guarantees must override
322     * this method and document its concurrency properties.
323     * 
324     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
325     * 
326     * @param key key with which the specified value is associated
327     * @param value value to be associated with the specified key
328     * 
329     * @return the previous value associated with the specified key, or null if there was no
330     * mapping for the key. (A null return can also indicate that the map previously associated
331     * null with the key, if the implementation supports null values.)
332     * 
333     * @throws ClassCastException if the class of the specified key or value prevents it from being
334     * stored in this map (optional)
335     * 
336     * @throws NullPointerException if the specified key or value is null, and this map does not
337     * permit null keys or values
338     * 
339     * @throws IllegalArgumentException if some property of the specified key or value prevents it
340     * from being stored in this map
341     */
342    public V replace(K key, V value)
343    {
344        if (this.built) throw new AttemptedModificationException(ROTM);
345        return super.replace(key, value); 
346    }
347
348    /**
349     * Replaces each entry's value with the result of invoking the given function on that entry
350     * until all entries have been processed or the function throws an exception. Exceptions thrown
351     * by the function are relayed to the caller.
352     * 
353     * <BR /><BR />The default implementation is equivalent to, for this map:
354     * 
355     * <DIV CLASS=EXAMPLE>{@code
356     * for (Map.Entry<K, V> entry : map.entrySet())
357     *      entry.setValue(function.apply(entry.getKey(), entry.getValue()));
358     * }</DIV>
359     * 
360     * <BR />The default implementation makes no guarantees about synchronization or atomicity
361     * properties of this method. Any implementation providing atomicity guarantees must override
362     * this method and document its concurrency properties.
363     * 
364     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
365     * 
366     * @param function - the function to apply to each entry
367     * 
368     * @throws ClassCastException if the class of a replacement value prevents it from being stored
369     * in this map (optional)
370     * 
371     * @throws NullPointerException if the specified function is null, or if a replacement value is
372     * null and this map does not permit null values (optional)
373     * 
374     * @throws IllegalArgumentException - if some property of a replacement value prevents it from
375     * being stored in this map (optional)
376     * 
377     * @throws ConcurrentModificationException if an entry is found to be removed during iteration
378     */
379    public void replaceAll(BiFunction<? super K, ? super V, ? extends V> function)
380    {
381        if (this.built) throw new AttemptedModificationException(ROTM);
382        super.replaceAll(function); 
383    }
384
385
386    // ********************************************************************************************
387    // ********************************************************************************************
388    // Methods inherited from class java.util.TreeMap
389    // ********************************************************************************************
390    // ********************************************************************************************
391
392
393    // ceilingEntry, ceilingKey, comparator, containsKey, containsValue, descendingKeySet,
394    // descendingMap, entrySet, firstEntry, firstKey, floorEntry, floorKey, forEach, get, headMap,
395    // headMap, higherEntry, higherKey, keySet, lastEntry, lastKey, lowerEntry, lowerKey,
396    // navigableKeySet, size, subMap, subMap, tailMap, tailMap, values
397    // 
398    // Introspection Only: ceilingEntry, ceilingKey, comparator, containsKey, containsValue,
399    //                     firstEntry, firstKey, floorEntry, floorKey, forEach, get, higherEntry,
400    //                     higherKey, lastEntry, lastKey, lowerEntry, lowerKey, size
401    // 
402    // Potential-Mutator: descendingKeySet, descendingMap, entrySet, headMap, headMap, keySet,
403    //                    navigableKeySet, subMap, subMap, tailMap, tailMap, values
404    //
405    // Methods declared in interface java.util.Map
406    // compute, computeIfAbsent, computeIfPresent, getOrDefault, hashCode, isEmpty, merge,
407    // putIfAbsent, remove
408
409    /**
410     * Restricts a back-door into the underlying data-structure.
411     * <EMBED CLASS='external-html' DATA-RET_TYPE=NavigableSet DATA-FILE-ID=UNMODIFIABLE>
412     * @return a {@code java.util.NavigableSet} that cannot modify this {@code TreeMap-Builder}
413     */
414    public NavigableSet<K> descendingKeySet()
415    { return Collections.unmodifiableNavigableSet(super.descendingMap().navigableKeySet()); }
416
417    // *** Java-HTML: 
418    // Looking at the JDK-21 Code for TreeMap, descendingKeySet() just calls the stuff lited below
419    // This supbstitution has to happen, or else the AccessDeniedException throws
420
421    NavigableSet<K> _descendingKeySet(ReadOnlyTreeMap.AccessBadge friendClassBadge)
422    { return super.descendingMap().navigableKeySet(); /* descendingKeySet(); */}
423
424    /**
425     * Restricts a back-door into the underlying data-structure.
426     * <EMBED CLASS='external-html' DATA-RET_TYPE=NavigableMap DATA-FILE-ID=UNMODIFIABLE>
427     * @return a {@code java.util.NavigableMap} that cannot modify this {@code TreeMap-Builder}
428     */
429    public NavigableMap<K,V> descendingMap()
430    { return Collections.unmodifiableNavigableMap(super.descendingMap()); }
431
432    NavigableMap<K,V> _descendingMap(ReadOnlyTreeMap.AccessBadge friendClassBadge)
433    { return super.descendingMap(); }
434
435    /**
436     * Restricts a back-door into the underlying data-structure.
437     * <EMBED CLASS='external-html' DATA-RET_TYPE=Set DATA-FILE-ID=UNMODIFIABLE>
438     * @return a {@code java.util.Set} that cannot modify this {@code TreeMap-Builder}
439     */
440    public Set<Map.Entry<K,V>> entrySet()
441    { return Collections.unmodifiableSet(super.entrySet());  }
442
443    Set<Map.Entry<K,V>> _entrySet(ReadOnlyTreeMap.AccessBadge friendClassBadge)
444    { return super.entrySet(); }
445
446    /**
447     * Restricts a back-door into the underlying data-structure.
448     * <EMBED CLASS='external-html' DATA-RET_TYPE=SortedMap DATA-FILE-ID=UNMODIFIABLE>
449     * @return a {@code java.util.SortedMap} that cannot modify this {@code TreeMap-Builder}
450     */
451    public SortedMap<K,V> headMap(K toKey)
452    { return Collections.unmodifiableSortedMap(super.headMap(toKey, false));  }
453
454    // *** Java-HTML: 
455    // Looking at the JDK-21 Code for TreeMap, headMap(K) just calls headMap(K, boolean)
456    // This supbstitution has to happen, or else the AccessDeniedException throws
457
458    SortedMap<K,V> _headMap(K toKey, ReadOnlyTreeMap.AccessBadge friendClassBadge)
459    { return super.headMap(toKey, false); }
460
461    /**
462     * Restricts a back-door into the underlying data-structure.
463     * <EMBED CLASS='external-html' DATA-RET_TYPE=NavigableMap DATA-FILE-ID=UNMODIFIABLE>
464     * @return a {@code java.util.NavigableMap} that cannot modify this {@code TreeMap-Builder}
465     */
466    public NavigableMap<K,V> headMap(K toKey, boolean inclusive)
467    { return Collections.unmodifiableNavigableMap(super.headMap(toKey, inclusive)); }
468
469    NavigableMap<K,V> _headMap
470        (K toKey, boolean inclusive, ReadOnlyTreeMap.AccessBadge friendClassBadge)
471    { return super.headMap(toKey, inclusive); }
472
473    /**
474     * Restricts a back-door into the underlying data-structure.
475     * <EMBED CLASS='external-html' DATA-RET_TYPE=Set DATA-FILE-ID=UNMODIFIABLE>
476     * @return a {@code java.util.Set} that cannot modify this {@code TreeMap-Builder}
477     */
478    public Set<K> keySet()
479    { return Collections.unmodifiableSet(super.navigableKeySet()); }
480
481    // *** Java-HTML: 
482    // Looking at the JDK-21 Code for TreeMap, keySet() just calls navigableKeySet()
483    // This supbstitution has to happen, or else the AccessDeniedException throws
484
485    Set<K> _keySet(ReadOnlyTreeMap.AccessBadge friendClassBadge)
486    { return /* *** Java-HTML: super.keySet(); */ super.navigableKeySet(); }
487
488    /**
489     * Restricts a back-door into the underlying data-structure.
490     * <EMBED CLASS='external-html' DATA-RET_TYPE=NavigableSet DATA-FILE-ID=UNMODIFIABLE>
491     * @return a {@code java.util.NavigableSet} that cannot modify this {@code TreeMap-Builder}
492     */
493    public NavigableSet<K> navigableKeySet()
494    { return Collections.unmodifiableNavigableSet(super.navigableKeySet()); }
495
496    NavigableSet<K> _navigableKeySet(ReadOnlyTreeMap.AccessBadge friendClassBadge)
497    { return super.navigableKeySet(); }
498
499    /**
500     * Restricts a back-door into the underlying data-structure.
501     * <EMBED CLASS='external-html' DATA-RET_TYPE=NavigableMap DATA-FILE-ID=UNMODIFIABLE>
502     * @return a {@code java.util.NavigableMap} that cannot modify this {@code TreeMap-Builder}
503     */
504    public NavigableMap<K,V> subMap
505        (K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)
506    {
507        return Collections.unmodifiableNavigableMap
508            (super.subMap(fromKey, fromInclusive, toKey, toInclusive));
509    }
510
511    NavigableMap<K,V> _subMap(
512            K fromKey, boolean fromInclusive, K toKey, boolean toInclusive,
513            ReadOnlyTreeMap.AccessBadge friendClassBadge
514        )
515    { return super.subMap(fromKey, fromInclusive, toKey, toInclusive); }
516
517    /**
518     * Restricts a back-door into the underlying data-structure.
519     * <EMBED CLASS='external-html' DATA-RET_TYPE=SortedMap DATA-FILE-ID=UNMODIFIABLE>
520     * @return a {@code java.util.SortedMap} that cannot modify this {@code TreeMap-Builder}
521     */
522    public SortedMap<K,V> subMap(K fromKey, K toKey)
523    { return Collections.unmodifiableSortedMap(super.subMap(fromKey, true, toKey, false));  }
524
525    // *** Java-HTML: 
526    // Looking at the JDK-21 Code for TreeMap, subMap(K, K) invokes subMap(K, boolean, K, boolean)
527    // This supbstitution has to happen, or else the AccessDeniedException throws
528
529    SortedMap<K,V> _subMap(K fromKey, K toKey, ReadOnlyTreeMap.AccessBadge friendClassBadge)
530    { return super.subMap(fromKey, true, toKey, false); }
531
532    /**
533     * Restricts a back-door into the underlying data-structure.
534     * <EMBED CLASS='external-html' DATA-RET_TYPE=SortedMap DATA-FILE-ID=UNMODIFIABLE>
535     * @return a {@code java.util.SortedMap} that cannot modify this {@code TreeMap-Builder}
536     */
537    public SortedMap<K,V> tailMap(K fromKey)
538    { return Collections.unmodifiableSortedMap(super.tailMap(fromKey, true));  }
539
540    // *** Java-HTML: 
541    // Looking at the JDK-21 Code for TreeMap, tailMap(K) just calls tailMap(K, boolean)
542    // This supbstitution has to happen, or else the AccessDeniedException throws
543
544    SortedMap<K,V> _tailMap(K fromKey, ReadOnlyTreeMap.AccessBadge friendClassBadge)
545    { return super.tailMap(fromKey, true); }
546
547    /**
548     * Restricts a back-door into the underlying data-structure.
549     * <EMBED CLASS='external-html' DATA-RET_TYPE=NavigableMap DATA-FILE-ID=UNMODIFIABLE>
550     * @return a {@code java.util.NavigableMap} that cannot modify this {@code TreeMap-Builder}
551     */
552    public NavigableMap<K,V> tailMap(K fromKey, boolean inclusive)
553    { return Collections.unmodifiableNavigableMap(super.tailMap(fromKey, inclusive)); }
554
555    NavigableMap<K,V> _tailMap
556        (K fromKey, boolean inclusive, ReadOnlyTreeMap.AccessBadge friendClassBadge)
557    { return super.tailMap(fromKey, inclusive); }
558
559    /**
560     * Restricts a back-door into the underlying data-structure.
561     * <EMBED CLASS='external-html' DATA-RET_TYPE=Collection DATA-FILE-ID=UNMODIFIABLE>
562     * @return a {@code java.util.Collection} that cannot modify this {@code TreeMap-Builder}
563     */
564    public Collection<V> values()
565    { return Collections.unmodifiableCollection(super.values()); }
566
567    Collection<V> _values(ReadOnlyTreeMap.AccessBadge friendClassBadge)
568    { return super.values(); }
569
570
571    // ********************************************************************************************
572    // ********************************************************************************************
573    // Methods declared in interface java.util.Map 
574    // ********************************************************************************************
575    // ********************************************************************************************
576
577    // RE-COPIED FROM ABOVE
578    // compute, computeIfAbsent, computeIfPresent, getOrDefault, hashCode, isEmpty, merge,
579    // putIfAbsent, remove
580    //
581    // Introspection Methods: getOrDefault, hashCode, isEmpty
582    // Mutator Methods: compute, computeIfAbsent, computeIfPresent, merge, putIfAbsent, remove
583
584    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
585    public V compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
586    {
587        if (this.built) throw new AttemptedModificationException(ROTM);
588        return super.compute(key, remappingFunction);
589    }
590
591    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
592    public V computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
593    {
594        if (this.built) throw new AttemptedModificationException(ROTM);
595        return super.computeIfAbsent(key, mappingFunction);
596    }
597
598    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
599    public V computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
600    {
601        if (this.built) throw new AttemptedModificationException(ROTM);
602        return super.computeIfPresent(key, remappingFunction);
603    }
604
605    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
606    public V merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
607    {
608        if (this.built) throw new AttemptedModificationException(ROTM);
609        return super.merge(key, value, remappingFunction);
610    }
611
612    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
613    public  V putIfAbsent(K key, V value)
614    {
615        if (this.built) throw new AttemptedModificationException(ROTM);
616        return super.putIfAbsent(key, value);
617    }
618
619    /** <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR> */
620    public boolean remove(Object key, Object value)
621    {
622        if (this.built) throw new AttemptedModificationException(ROTM);
623        return super.remove(key, value);
624    }
625
626
627    // ********************************************************************************************
628    // ********************************************************************************************
629    // java.lang.Object & Cloneable
630    // ********************************************************************************************
631    // ********************************************************************************************
632
633
634    /**
635     * Compares the specified Object with this Builder for equality, as per the definition in the
636     * private and internal field {@code 'treeMap'}.
637     *
638     * @param  o object to be compared for equality with this {@code ROTreeMapBuilder} instance
639     * @return true if the specified Object is equal to this Builder
640     */
641    public boolean equals(Object o)
642    {
643        if (this == o) return true;
644        if (! (o instanceof ROTreeMapBuilder)) return false;
645        return super.equals((TreeMap) o);
646    }
647
648    /**
649     * Clones this instance' of {@code ROTreeMapBuilder}.
650     * 
651     * <BR /><BR />The clone that's returned has had it's internal {@code 'built'} boolean-flag set
652     * {@code FALSE}
653     * 
654     * @return a clone of this builder
655     */
656    public synchronized ROTreeMapBuilder<K, V> clone()
657    { return new ROTreeMapBuilder<>(this); }
658
659    private ROTreeMapBuilder(ROTreeMapBuilder<K, V> rotmb)
660    { super(rotmb); this.built=false; }
661}