Class ROTreeMapBuilder<K,​V>

  • Type Parameters:
    K - the type of keys maintained by this map
    V - the type of mapped values
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.util.Map<K,​V>, java.util.NavigableMap<K,​V>, java.util.SortedMap<K,​V>
    public final class ROTreeMapBuilder<K,​V>
extends java.util.TreeMap<K,​V>
implements java.lang.Cloneable, java.io.Serializable
    This class was originally copied from GitHub's Open-JDK Account. Though the original file has been modified, few changes were applied to the Javadoc Commenting. Method and parameter names & types have not been modified whatsoever. This file may be viewed on the GitHub Archive for Java Package java.util.*

    The Original '.java' Source-File's Header-Copyright Information is included here: File Copyright. Within that Copyright Notice, it is suggested that a copy of the GNU Public License V2 also be included alongside.
    A Copy of Java's TreeMap class; used for building a ReadOnlyTreeMap. Maintains an internal and inaccessible TreeMap<E> instance. Upon build completion, this instance is passed to the ReadOnlyTreeMap instance and stored there.

    The internal data-structure is not exposed by any method provided in this API. It is guaranteed that the contents of a ReadOnlyTreeMap will not be modified.

    Note: The "RO Builder Classes" are somewhat superfluous (a little)

    The art of any solid "Read-Only" Data-Structure Class-API is providing an intelligent means of actually inserting Data into a supposedly-read-only class. In this package, the most direct and efficient way of doing so is just to use one of the myriad constructors offered by the ReadOnly Data-Classes.

    Another sound way of creating any "ReadOnly-XX" Data-Structure, is to simply populate the corresponding java.util.XX class instance, and pass that instance your ReadOnly-X Constructor. The constructor actually copies the data out of the original structure, and saves it to its own private & internal data-structure in order to guarantee the immutability contract.

    But what about a situation where there is a TreeMap that is being populated by a very large number elements? It would likely be of benefit to skip the data-copying step for performance reasons! If so, then a builder can improve performance quite a bit. The real value of using a "Builder" rather than one of the ReadOnlyTreeMap constructors is that this Builder's build() method doesn't actually have any kind of data-copy step at all!

    Also, of some interest, is that this class inherits the original Java-Class java.util.TreeMap (explained further, below), making it extremely easy to use.

    Inherits java.util.TreeMap
    This class may be passed to any Data-Building Method that accepts a TreeMap, because it inherits from that class. Any implementation that can populate a TreeMap can also populate this builder.

    Efficiency Improvement:
    This class is nothing but a set of wrapper methods. It is being provided as an alternate, and possibly more efficient, way to construct a ReadOnlyTreeMap.

    This class inherits the Standard JDK Collection-Framework Class java.util.TreeMap, and adds a single boolean field named 'built' that, once switched to 'true', will block any subsequent attempts to mutate the underlying data-structure.

    With a TreeMap having more than, say, 10,000 items, the cost of copying the internal TreeMap (which is necessary to construct any Read-Only Class) would perhaps be much too high. Instead, by making use of class ROTreeMapBuilder, there is no need to run any kind of internal-data data-copying step at all.

    Simply put all data into the Builder, using any / all standard Java-JDK TreeMap methods, and when the build() method is invoked, an internal flag is set which will wholly prohibit any further mutation of the data in your builder - thereby allowing the Builder, itself, to be used as the ReadOnlyTreeMap's internal Data-Structure.
    See Also:
    ReadOnlyTreeMap, Serialized Form


    • Nested Class Summary

      • Nested classes/interfaces inherited from class java.util.AbstractMap

        java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static long serialVersionUID

    • Constructor Summary

      Constructors 
      Constructor Description
      ROTreeMapBuilder()
      Constructs a new, empty ROTreeMapBuilder (tree map), using the natural ordering of its keys.
      ROTreeMapBuilder​(Comparator<? super K> comparator)
      Constructs a new, empty ROTreeMapBuilder (tree map), ordered according to the given comparator.
      ROTreeMapBuilder​(Map<? extends K,​? extends V> m)
      Constructs a new ROTreeMapBuilder (tree map) containing the same mappings as the given map, ordered according to the natural ordering of its keys.
      ROTreeMapBuilder​(SortedMap<K,​? extends V> m)
      Constructs a new ROTreeMapBuilder (tree map) containing the same mappings and using the same ordering as the specified sorted map.

    • Method Summary

       
      Convert this Builder into a ReadOnlyTreeMap Instance
      Modifier and Type Method
      ReadOnlyTreeMap<K,​V> build()
      Simply transfers 'this' instance' internal TreeMap to the ReadOnlyTreeMap Wrapper-Class.
       
      Insert Entries into this Read-Only-Map Builder
      Modifier and Type Method
      V put​(K key, V value)
      Associates the specified value with the specified key in this map.
      void putAll​(Map<? extends K,​? extends V> map)
      Copies all of the mappings from the specified map to this map.
      V putIfAbsent​(K key, V value)
       
      Remove Entries from this Read-Only-Map Builder
      Modifier and Type Method
      void clear()
      Removes all of the mappings from this map.
      V remove​(Object key)
      Removes the mapping for this key from this TreeMap if present.
      boolean remove​(Object key, Object value)
       
      Compute Entries, and then Insert them into this Map Builder
      Modifier and Type Method
      V compute​(K key, BiFunction<? super K,​? super V,​? extends V> remappingFunction)
      V computeIfAbsent​(K key, Function<? super K,​? extends V> mappingFunction)
      V computeIfPresent​(K key, BiFunction<? super K,​? super V,​? extends V> remappingFunction)
      V merge​(K key, V value, BiFunction<? super V,​? super V,​? extends V> remappingFunction)
       
      Replace Map Entries
      Modifier and Type Method
      V replace​(K key, V value)
      Replaces the entry for the specified key only if it is currently mapped to some value.
      boolean replace​(K key, V oldValue, V newValue)
      Replaces the entry for the specified key only if currently mapped to the specified value.
      void replaceAll​(BiFunction<? super K,​? super V,​? extends V> function)
      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.
       
      Poll (Remove & Return) Map Entries
      Modifier and Type Method
      Map.Entry<K,​V> pollFirstEntry()
      Removes and returns a key-value mapping associated with the least key in this map, or null if the map is empty.
      Map.Entry<K,​V> pollLastEntry()
      Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.
       
      Mutable / Read-Write View Generators - Return Instances with Unmodifiable-Wrappers
      Modifier and Type Method
      NavigableSet<K> descendingKeySet()
      Restricted-Access Instance
      NavigableMap<K,​V> descendingMap()
      Restricted-Access Instance
      Set<Map.Entry<K,​V>> entrySet()
      Restricted-Access Instance
      SortedMap<K,​V> headMap​(K toKey)
      Restricted-Access Instance
      NavigableMap<K,​V> headMap​(K toKey, boolean inclusive)
      Restricted-Access Instance
      Set<K> keySet()
      Restricted-Access Instance
      NavigableSet<K> navigableKeySet()
      Restricted-Access Instance
      NavigableMap<K,​V> subMap​(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)
      Restricted-Access Instance
      SortedMap<K,​V> subMap​(K fromKey, K toKey)
      Restricted-Access Instance
      SortedMap<K,​V> tailMap​(K fromKey)
      Restricted-Access Instance
      NavigableMap<K,​V> tailMap​(K fromKey, boolean inclusive)
      Restricted-Access Instance
      Collection<V> values()
      Restricted-Access Instance
       
      Methods: class java.lang.Object
      Modifier and Type Method
      boolean equals​(Object o)
      Compares the specified Object with this Builder for equality, as per the definition in the private and internal field 'treeMap'.
       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method
      ROTreeMapBuilder<K,​V> clone()
      Clones this instance' of ROTreeMapBuilder.

      • Methods inherited from class java.util.TreeMap

        ceilingEntry, ceilingKey, comparator, containsKey, containsValue, firstEntry, firstKey, floorEntry, floorKey, forEach, get, higherEntry, higherKey, lastEntry, lastKey, lowerEntry, lowerKey, size

      • Methods inherited from class java.util.AbstractMap

        hashCode, isEmpty, toString

      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.util.Map

        getOrDefault, hashCode, isEmpty

    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final long serialVersionUID = 1;

    • Constructor Detail

      • ROTreeMapBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROTreeMapBuilder()
        Constructs a new, empty ROTreeMapBuilder (tree map), using the natural ordering of its keys. All keys inserted into the map must implement the Comparable interface. Furthermore, all such keys must be mutually comparable: k1.compareTo(k2) must not throw a ClassCastException for any keys k1 and 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 put(Object key, Object value) call will throw a ClassCastException.

      • ROTreeMapBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROTreeMapBuilder​(java.util.Comparator<? super K> comparator)
        Constructs a new, empty ROTreeMapBuilder (tree map), ordered according to the given comparator. All keys inserted into the map must be mutually comparable by the given comparator: comparator.compare(k1, k2) must not throw a ClassCastException for any keys k1 and k2 in the map. If the user attempts to put a key into the map that violates this constraint, the put(Object key, Object value) call will throw a ClassCastException.
        Parameters:
        comparator - the comparator that will be used to order this map. If null, the natural ordering of the keys will be used.
        Code:
        Exact Constructor Body:
         super(comparator);

      • ROTreeMapBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROTreeMapBuilder​(java.util.Map<? extends K,​? extends V> m)
        Constructs a new ROTreeMapBuilder (tree map) containing the same mappings as the given map, ordered according to the natural ordering of its keys. All keys inserted into the new map must implement the Comparable interface. Furthermore, all such keys must be mutually comparable: k1.compareTo(k2) must not throw a ClassCastException for any keys k1 and k2 in the map. This method runs in n*log(n) time.
        Parameters:
        m - the map whose mappings are to be placed in this map
        Throws:
        java.lang.ClassCastException - if the keys in m are not Comparable, or are not mutually comparable
        java.lang.NullPointerException - if the specified map is null
        Code:
        Exact Constructor Body:
         super(m);

      • ROTreeMapBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROTreeMapBuilder​(java.util.SortedMap<K,​? extends V> m)
        Constructs a new ROTreeMapBuilder (tree map) containing the same mappings and using the same ordering as the specified sorted map. This method runs in linear time.
        Parameters:
        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:
        java.lang.NullPointerException - if the specified map is null
        Code:
        Exact Constructor Body:
         super(m);

    • Method Detail

      • build

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeMap<K,​V> build()
        Simply transfers 'this' instance' internal TreeMap to the ReadOnlyTreeMap Wrapper-Class.
        Returns:
        a newly constructed ReadOnlyTreeMap "Wrapper-Class", shielding the internal 'treeMap' private-field from any modification.
        Code:
        Exact Method Body:
         this.built = true;

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

      • putAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void putAll​(java.util.Map<? extends K,​? extends V> map)
        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.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        putAll in interface java.util.Map<K,​V>
        Overrides:
        putAll in class java.util.TreeMap<K,​V>
        Parameters:
        map - mappings to be stored in this map
        Throws:
        java.lang.ClassCastException - if the class of a key or value in the specified map prevents it from being stored in this map
        java.lang.NullPointerException - if the specified map is null or the specified map contains a null key and this map does not permit null keys
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 super.putAll(map);

      • put

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V put​(K key,
             V value)
        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.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        put in interface java.util.Map<K,​V>
        Overrides:
        put in class java.util.TreeMap<K,​V>
        Parameters:
        key - key with which the specified value is to be associated
        value - value to be associated with the specified key
        Returns:
        the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that the map previously associated null with key.)
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.put(key, value);

      • remove

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V remove​(java.lang.Object key)
        Removes the mapping for this key from this TreeMap if present.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        remove in interface java.util.Map<K,​V>
        Overrides:
        remove in class java.util.TreeMap<K,​V>
        Parameters:
        key - key for which mapping should be removed
        Returns:
        the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that the map previously associated null with key.)
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.remove(key);

      • clear

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void clear()
        Removes all of the mappings from this map. The map will be empty after this call returns.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        clear in interface java.util.Map<K,​V>
        Overrides:
        clear in class java.util.TreeMap<K,​V>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 super.clear();

      • pollFirstEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map.Entry<K,​V> pollFirstEntry()
        Removes and returns a key-value mapping associated with the least key in this map, or null if the map is empty.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        pollFirstEntry in interface java.util.NavigableMap<K,​V>
        Overrides:
        pollFirstEntry in class java.util.TreeMap<K,​V>
        Returns:
        the removed first entry of this map, or null if this map is empty
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.pollFirstEntry();

      • pollLastEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map.Entry<K,​V> pollLastEntry()
        Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        pollLastEntry in interface java.util.NavigableMap<K,​V>
        Overrides:
        pollLastEntry in class java.util.TreeMap<K,​V>
        Returns:
        the removed last entry of this map, or null if this map is empty
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.pollLastEntry();

      • replace

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean replace​(K key,
                       V oldValue,
                       V newValue)


        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build(). Replaces the entry for the specified key only if currently mapped to the specified value.

        The default implementation is equivalent to, for this map: 

         if (map.containsKey(key) && Objects.equals(map.get(key), oldValue))
 {
     map.put(key, newValue);
     return true;
 }
 return false;


        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.
        Specified by:
        replace in interface java.util.Map<K,​V>
        Overrides:
        replace in class java.util.TreeMap<K,​V>
        Parameters:
        key - key with which the specified value is associated
        oldValue - value expected to be associated with the specified key
        newValue - value to be associated with the specified key
        Returns:
        TRUE if the value was replaced
        Throws:
        java.lang.ClassCastException - if the class of a specified key or value prevents it from being stored in this map
        java.lang.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)
        java.lang.IllegalArgumentException - if some property of a specified key or value prevents it from being stored in this map
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.replace(key, oldValue, newValue);

      • replace

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V replace​(K key,
                 V value)
        Replaces the entry for the specified key only if it is currently mapped to some value.

        The default implementation is equivalent to, for this map:

        Example:
         return map.containsKey(key)
      ? map.put(key, value);
      : 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.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        replace in interface java.util.Map<K,​V>
        Overrides:
        replace in class java.util.TreeMap<K,​V>
        Parameters:
        key - key with which the specified value is associated
        value - value to be associated with the specified key
        Returns:
        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:
        java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map (optional)
        java.lang.NullPointerException - if the specified key or value is null, and this map does not permit null keys or values
        java.lang.IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this map
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.replace(key, value);

      • replaceAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void replaceAll​
            (java.util.function.BiFunction<? super K,​? super V,​? extends V> function)
        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:

        Example:
         for (Map.Entry<K, V> entry : map.entrySet())
      entry.setValue(function.apply(entry.getKey(), entry.getValue()));

        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.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        replaceAll in interface java.util.Map<K,​V>
        Overrides:
        replaceAll in class java.util.TreeMap<K,​V>
        Parameters:
        function - - the function to apply to each entry
        Throws:
        java.lang.ClassCastException - if the class of a replacement value prevents it from being stored in this map (optional)
        java.lang.NullPointerException - if the specified function is null, or if a replacement value is null and this map does not permit null values (optional)
        java.lang.IllegalArgumentException - - if some property of a replacement value prevents it from being stored in this map (optional)
        java.util.ConcurrentModificationException - if an entry is found to be removed during iteration
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 super.replaceAll(function);

      • descendingKeySet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.NavigableSet<K> descendingKeySet()
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned NavigableSet in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this NavigableSet (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        descendingKeySet in interface java.util.NavigableMap<K,​V>
        Overrides:
        descendingKeySet in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.NavigableSet that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableNavigableSet(super.descendingMap().navigableKeySet());

      • descendingMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.NavigableMap<K,​V> descendingMap()
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned NavigableMap in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this NavigableMap (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        descendingMap in interface java.util.NavigableMap<K,​V>
        Overrides:
        descendingMap in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.NavigableMap that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableNavigableMap(super.descendingMap());

      • entrySet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Set<java.util.Map.Entry<K,​V>> entrySet()
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned Set in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this Set (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        entrySet in interface java.util.Map<K,​V>
        Specified by:
        entrySet in interface java.util.SortedMap<K,​V>
        Overrides:
        entrySet in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.Set that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableSet(super.entrySet());

      • headMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.SortedMap<K,​V> headMap​(K toKey)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned SortedMap in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this SortedMap (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        headMap in interface java.util.NavigableMap<K,​V>
        Specified by:
        headMap in interface java.util.SortedMap<K,​V>
        Overrides:
        headMap in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.SortedMap that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableSortedMap(super.headMap(toKey, false));

      • headMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.NavigableMap<K,​V> headMap​(K toKey,
                                                 boolean inclusive)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned NavigableMap in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this NavigableMap (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        headMap in interface java.util.NavigableMap<K,​V>
        Overrides:
        headMap in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.NavigableMap that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableNavigableMap(super.headMap(toKey, inclusive));

      • keySet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Set<K> keySet()
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned Set in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this Set (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        keySet in interface java.util.Map<K,​V>
        Specified by:
        keySet in interface java.util.SortedMap<K,​V>
        Overrides:
        keySet in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.Set that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableSet(super.navigableKeySet());

      • navigableKeySet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.NavigableSet<K> navigableKeySet()
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned NavigableSet in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this NavigableSet (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        navigableKeySet in interface java.util.NavigableMap<K,​V>
        Overrides:
        navigableKeySet in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.NavigableSet that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableNavigableSet(super.navigableKeySet());

      • subMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.NavigableMap<K,​V> subMap​(K fromKey,
                                                boolean fromInclusive,
                                                K toKey,
                                                boolean toInclusive)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned NavigableMap in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this NavigableMap (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        subMap in interface java.util.NavigableMap<K,​V>
        Overrides:
        subMap in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.NavigableMap that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableNavigableMap
     (super.subMap(fromKey, fromInclusive, toKey, toInclusive));

      • subMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.SortedMap<K,​V> subMap​(K fromKey,
                                             K toKey)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned SortedMap in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this SortedMap (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        subMap in interface java.util.NavigableMap<K,​V>
        Specified by:
        subMap in interface java.util.SortedMap<K,​V>
        Overrides:
        subMap in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.SortedMap that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableSortedMap(super.subMap(fromKey, true, toKey, false));

      • tailMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.SortedMap<K,​V> tailMap​(K fromKey)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned SortedMap in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this SortedMap (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        tailMap in interface java.util.NavigableMap<K,​V>
        Specified by:
        tailMap in interface java.util.SortedMap<K,​V>
        Overrides:
        tailMap in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.SortedMap that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableSortedMap(super.tailMap(fromKey, true));

      • tailMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.NavigableMap<K,​V> tailMap​(K fromKey,
                                                 boolean inclusive)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned NavigableMap in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this NavigableMap (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        tailMap in interface java.util.NavigableMap<K,​V>
        Overrides:
        tailMap in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.NavigableMap that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableNavigableMap(super.tailMap(fromKey, inclusive));

      • values

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Collection<V> values()
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned Collection in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying TreeMap that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this Collection (which possesses methods for mutating the TreeMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyTreeMap that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this TreeMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        values in interface java.util.Map<K,​V>
        Specified by:
        values in interface java.util.SortedMap<K,​V>
        Overrides:
        values in class java.util.TreeMap<K,​V>
        Returns:
        a java.util.Collection that cannot modify this TreeMap-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableCollection(super.values());

      • compute

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V compute​
            (K key,
             java.util.function.BiFunction<? super K,​? super V,​? extends V> remappingFunction)


        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        compute in interface java.util.Map<K,​V>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.compute(key, remappingFunction);

      • computeIfAbsent

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V computeIfAbsent​
            (K key,
             java.util.function.Function<? super K,​? extends V> mappingFunction)


        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        computeIfAbsent in interface java.util.Map<K,​V>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.computeIfAbsent(key, mappingFunction);

      • computeIfPresent

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V computeIfPresent​
            (K key,
             java.util.function.BiFunction<? super K,​? super V,​? extends V> remappingFunction)


        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        computeIfPresent in interface java.util.Map<K,​V>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.computeIfPresent(key, remappingFunction);

      • merge

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V merge​
            (K key,
             V value,
             java.util.function.BiFunction<? super V,​? super V,​? extends V> remappingFunction)


        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        merge in interface java.util.Map<K,​V>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.merge(key, value, remappingFunction);

      • putIfAbsent

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V putIfAbsent​(K key,
                     V value)


        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        putIfAbsent in interface java.util.Map<K,​V>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.putIfAbsent(key, value);

      • remove

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean remove​(java.lang.Object key,
                      java.lang.Object value)


        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        remove in interface java.util.Map<K,​V>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTM);
 return super.remove(key, value);

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object o)
        Compares the specified Object with this Builder for equality, as per the definition in the private and internal field 'treeMap'.
        Specified by:
        equals in interface java.util.Map<K,​V>
        Overrides:
        equals in class java.util.AbstractMap<K,​V>
        Parameters:
        o - object to be compared for equality with this ROTreeMapBuilder instance
        Returns:
        true if the specified Object is equal to this Builder
        Code:
        Exact Method Body:
         if (this == o) return true;
 if (! (o instanceof ROTreeMapBuilder)) return false;
 return super.equals((TreeMap) o);

      • clone

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public ROTreeMapBuilder<K,​V> clone()
        Clones this instance' of ROTreeMapBuilder.

        The clone that's returned has had it's internal 'built' boolean-flag set FALSE
        Overrides:
        clone in class java.util.TreeMap<K,​V>
        Returns:
        a clone of this builder
        Code:
        Exact Method Body:
         return new ROTreeMapBuilder<>(this);