Class ROHashtableBuilder<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>
    public final class ROHashtableBuilder<K,​V>
extends java.util.Hashtable<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 Hashtable class; used for building a ReadOnlyHashtable. Maintains an internal and inaccessible Hashtable<K, V> instance. Upon build completion, this instance is passed to the ReadOnlyHashtable 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 ReadOnlyHashtable 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 Hashtable 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 ReadOnlyHashtable 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.Hashtable (explained further, below), making it extremely easy to use.

    Inherits java.util.Hashtable
    This class may be passed to any Data-Building Method that accepts a Hashtable, because it inherits from that class. Any implementation that can populate a Hashtable 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 ReadOnlyHashtable.

    This class inherits the Standard JDK Collection-Framework Class java.util.Hashtable, 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 Hashtable having more than, say, 10,000 items, the cost of copying the internal Hashtable (which is necessary to construct any Read-Only Class) would perhaps be much too high. Instead, by making use of class ROHashtableBuilder, 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 Hashtable 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 ReadOnlyHashtable's internal Data-Structure.

    Synchronized Class Wrapper:
    This class is a Wrapper-Class for an internal, private Hashtable Field. Since this internal field is of a type that is a Thread-Safe Class, all of this internal class' methods are declared with the Java 'synchronized' keyword. You may look at the Oracle Java-Doc Pages for java.util.Hashtable to see it is Multi-Threaded-Friendly Type.

    This class maintains no internal data of its own (whatsoever!) This Wrapper-Class' methods, therefore, have not been declared using the 'sychronized' keyword. Adding the 'synchronized' modifier to these methods would be superfluous, and have no effect at all other than to cause a reduction in performance.

    Another way of saying this is that every single method in this class simply turns around and calls a method from java.util.Hashtable which is, itself, completely synchronized already. Thusly, these methods, here, don't need a second round of synchronization added.
    See Also:
    ReadOnlyHashtable, Serialized Form


    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static long serialVersionUID

    • Constructor Summary

      Constructors 
      Constructor Description
      ROHashtableBuilder()
      Constructs a new, empty ROHashtableBuilder with a default initial capacity (11) and load factor (0.75).
      ROHashtableBuilder​(int initialCapacity)
      Constructs a new, empty ROHashtableBuilder with the specified initial capacity and default load factor (0.75).
      ROHashtableBuilder​(int initialCapacity, float loadFactor)
      Constructs a new, empty ROHashtableBuilder with the specified initial capacity and the specified load factor.
      ROHashtableBuilder​(Map<? extends K,​? extends V> t)
      Constructs a new ROHashtableBuilder with the same mappings as the given Map.

    • Method Summary

       
      Convert this Builder into a ReadOnlyHashtable Instance
      Modifier and Type Method
      ReadOnlyHashtable<K,​V> build()
      Simply transfers 'this' instance' internal Hashtable to the ReadOnlyHashtable Wrapper-Class.
       
      Insert Entries into this Read-Only-Table Builder
      Modifier and Type Method
      V put​(K key, V value)
      Maps the specified key to the specified value in this hashtable.
      void putAll​(Map<? extends K,​? extends V> t)
      Copies all of the mappings from the specified map to this hashtable.
      V putIfAbsent​(K key, V value)
      If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns null, else returns the current value.
       
      Remove Entries from this Read-Only-Table Builder
      Modifier and Type Method
      void clear()
      Clears this hashtable so that it contains no keys.
      V remove​(Object key)
      Removes the key (and its corresponding value) from this hashtable.
      boolean remove​(Object key, Object value)
      Replaces the entry for the specified key only if currently mapped to the specified value.
       
      Compute Entries, and then Insert them into this Table Builder
      Modifier and Type Method
      V compute​(K key, BiFunction<? super K,​? super V,​? extends V> remappingFunction)
      Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).
      V computeIfAbsent​(K key, Function<? super K,​? extends V> mappingFunction)
      If the specified key is not already associated with a value (or is mapped to null), attempts to compute its value using the given mapping function and enters it into this map unless null.
      V computeIfPresent​(K key, BiFunction<? super K,​? super V,​? extends V> remappingFunction)
      If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value.
      V merge​(K key, V value, BiFunction<? super V,​? super V,​? extends V> remappingFunction)
      If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value.
       
      Replace Table 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.
       
      Mutable / Read-Write View Generators - Return Instances with Unmodifiable-Wrappers
      Modifier and Type Method
      Set<Map.Entry<K,​V>> entrySet()
      Restricted-Access Instance
      Set<K> keySet()
      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 'hashTable'.
       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method
      ROHashtableBuilder<K,​V> clone()
      Clones this instance' of ROHashtableBuilder.

      • Methods inherited from class java.util.Hashtable

        contains, containsKey, containsValue, elements, forEach, get, getOrDefault, hashCode, isEmpty, keys, rehash, size, toString

      • Methods inherited from class java.lang.Object

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

    • 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

      • ROHashtableBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashtableBuilder​(int initialCapacity,
                          float loadFactor)
        Constructs a new, empty ROHashtableBuilder with the specified initial capacity and the specified load factor.
        Parameters:
        initialCapacity - the initial capacity of the hashtable.
        loadFactor - the load factor of the hashtable.
        Throws:
        java.lang.IllegalArgumentException - if the initial capacity is les than zero, or if the load factor is nonpositive.
        Code:
        Exact Constructor Body:
         super(initialCapacity, loadFactor);

      • ROHashtableBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashtableBuilder​(int initialCapacity)
        Constructs a new, empty ROHashtableBuilder with the specified initial capacity and default load factor (0.75).
        Parameters:
        initialCapacity - the initial capacity of the hashtable.
        Throws:
        java.lang.IllegalArgumentException - if the initial capacity is less than zero.
        Code:
        Exact Constructor Body:
         super(initialCapacity);

      • ROHashtableBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashtableBuilder​(java.util.Map<? extends K,​? extends V> t)
        Constructs a new ROHashtableBuilder with the same mappings as the given Map. The builder is created with an initial capacity sufficient to hold the mappings in the given Map and a default load factor (0.75).
        Parameters:
        t - the map whose mappings are to be placed in this map.
        Throws:
        java.lang.NullPointerException - if the specified map is null.
        Code:
        Exact Constructor Body:
         // Note that below is the actual Hashtable Constructor Code.  It **DOES NOT** break the
 // "Read Only Contract" - Specifically, subsequent changes to 't' **WILL NOT** write
 // through into this internal hashTable instance.  They are copied / cloned "into" this map

 super(t);

    • Method Detail

      • build

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

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

      • put

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V put​(K key,
             V value)
        Maps the specified key to the specified value in this hashtable. Neither the key nor the value can be null.

        The value can be retrieved by calling the get method with a key that is equal to the original key.

        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable 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.Hashtable<K,​V>
        Parameters:
        key - the hashtable key
        value - the value
        Returns:
        the previous value of the specified key in this hashtable, or null if it did not have one
        Throws:
        java.lang.NullPointerException - if the key or value is null
        See Also:
        Hashtable.get(Object)
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 return super.put(key, value);

      • remove

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V remove​(java.lang.Object key)
        Removes the key (and its corresponding value) from this hashtable. This method does nothing if the key is not in the hashtable.

        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable 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.Hashtable<K,​V>
        Parameters:
        key - the key that needs to be removed
        Returns:
        the value to which the key had been mapped in this hashtable, or null if the key did not have a mapping
        Throws:
        java.lang.NullPointerException - if the key is null
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 return super.remove(key);

      • putAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void putAll​(java.util.Map<? extends K,​? extends V> t)
        Copies all of the mappings from the specified map to this hashtable. These mappings will replace any mappings that this hashtable had for any of the keys currently in the specified map.

        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable 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.Hashtable<K,​V>
        Parameters:
        t - mappings to be stored in this map
        Throws:
        java.lang.NullPointerException - if the specified map is null
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 super.putAll(t);

      • clear

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void clear()
        Clears this hashtable so that it contains no keys.

        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable 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.Hashtable<K,​V>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 super.clear();

      • 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: 

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


        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable 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.Hashtable<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
        java.lang.NullPointerException - if the specified function or the replacement value is null
        java.util.ConcurrentModificationException - - if an entry is found to be removed during iteration
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 super.replaceAll(function);

      • putIfAbsent

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V putIfAbsent​(K key,
                     V value)
        If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns null, else returns the current value.

        The default implementation is equivalent to, for this map: 

         V v = map.get(key);
 if (v == null) v = map.put(key, value);
 return v;


        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable field will throw an exception if invoked after a call to build().
        Specified by:
        putIfAbsent in interface java.util.Map<K,​V>
        Overrides:
        putIfAbsent in class java.util.Hashtable<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 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 key or value is of an inappropriate type for this map (optional)
        java.lang.NullPointerException - if the specified key or value is null
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 return super.putIfAbsent(key, value);

      • remove

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean remove​(java.lang.Object key,
                      java.lang.Object value)
        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;
 }
 
 else return false;


        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable 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.Hashtable<K,​V>
        Parameters:
        key - key with which the specified value is associated
        value - value expected 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
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 return super.remove(key, value);

      • replace

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean replace​(K key,
                       V oldValue,
                       V newValue)
        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;
 }
 
 else 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.

        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable 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.Hashtable<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 oldValue / newValue is null
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 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: 

         if (map.containsKey(key))    return map.put(key, value);
 else                         return null;


        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable 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.Hashtable<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
        java.lang.NullPointerException - if the specified key or value is null
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 return super.replace(key, value);

      • computeIfAbsent

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V computeIfAbsent​
            (K key,
             java.util.function.Function<? super K,​? extends V> mappingFunction)
        If the specified key is not already associated with a value (or is mapped to null), attempts to compute its value using the given mapping function and enters it into this map unless null.

        If the mapping function returns null, no mapping is recorded. If the mapping function itself throws an (unchecked) exception, the exception is rethrown, and no mapping is recorded. The most common usage is to construct a new object serving as an initial mapped value or memoized result, as in: 

         map.computeIfAbsent(key, k -> new Value(f(k)));

        Or to implement a multi-value map, Map<K,Collection<V>>, supporting multiple values per key: 

         map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);


        The mapping function should not modify this map during computation.

        This method will, on a best-effort basis, throw a ConcurrentModificationException if the mapping function modified this map during computation.

        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable field will throw an exception if invoked after a call to build().
        Specified by:
        computeIfAbsent in interface java.util.Map<K,​V>
        Overrides:
        computeIfAbsent in class java.util.Hashtable<K,​V>
        Parameters:
        key - key with which the specified value is to be associated
        mappingFunction - the mapping function to compute a value
        Returns:
        the current (existing or computed) value associated with the specified key, or null if the computed value is null
        Throws:
        java.util.ConcurrentModificationException - if it is detected that the mapping function modified this map
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 return computeIfAbsent(key, mappingFunction);

      • computeIfPresent

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V computeIfPresent​
            (K key,
             java.util.function.BiFunction<? super K,​? super V,​? extends V> remappingFunction)
        If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value. If the remapping function returns null, the mapping is removed.

        If the remapping function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

        The remapping function should not modify this map during computation.

        This method will, on a best-effort basis, throw a ConcurrentModificationException if the remapping function modified this map during computation.

        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable field will throw an exception if invoked after a call to build().
        Specified by:
        computeIfPresent in interface java.util.Map<K,​V>
        Overrides:
        computeIfPresent in class java.util.Hashtable<K,​V>
        Parameters:
        key - key with which the specified value is to be associated
        remappingFunction - the remapping function to compute a value
        Returns:
        the new value associated with the specified key, or null if none
        Throws:
        java.util.ConcurrentModificationException - if it is detected that the remapping function modified this map
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 return super.computeIfPresent(key, remappingFunction);

      • compute

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V compute​
            (K key,
             java.util.function.BiFunction<? super K,​? super V,​? extends V> remappingFunction)
        Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping). For example, to either create or append a String msg to a value mapping: 

         map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))


        (Method merge() is often simpler to use for such purposes.)

        If the remapping function returns null, the mapping is removed (or remains absent if initially absent). If the remapping function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

        The remapping function should not modify this map during computation.

        This method will, on a best-effort basis, throw a ConcurrentModificationException if the remapping function modified this map during computation.

        This method will, on a best-effort basis, throw a ConcurrentModificationException if the remapping function modified this map during computation.

        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable field will throw an exception if invoked after a call to build().
        Specified by:
        compute in interface java.util.Map<K,​V>
        Overrides:
        compute in class java.util.Hashtable<K,​V>
        Parameters:
        key - key with which the specified value is to be associated
        remappingFunction - the remapping function to compute a value
        Returns:
        the new value associated with the specified key, or null if none
        Throws:
        java.util.ConcurrentModificationException - if it is detected that the remapping function modified this map
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 return super.compute(key, remappingFunction);

      • merge

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V merge​
            (K key,
             V value,
             java.util.function.BiFunction<? super V,​? super V,​? extends V> remappingFunction)
        If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value. Otherwise, replaces the associated value with the results of the given remapping function, or removes if the result is null. This method may be of use when combining multiple mapped values for a key. For example, to either create or append a String msg to a value mapping: 

         map.merge(key, msg, String::concat)


        This method will, on a best-effort basis, throw a java.util.ConcurrentModificationException if the remapping function modified this map during computation.

        Mutator Method:
        This method modifies the contents of this class' internal Hashtable. Note that any method which modifies this internal Hashtable field will throw an exception if invoked after a call to build().
        Specified by:
        merge in interface java.util.Map<K,​V>
        Overrides:
        merge in class java.util.Hashtable<K,​V>
        Parameters:
        key - key with which the resulting value is to be associated
        value - the non-null value to be merged with the existing value associated with the key or, if no existing value or a null value is associated with the key, to be associated with the key
        remappingFunction - the remapping function to recompute a value if present
        Returns:
        the new value associated with the specified key, or null if no value is associated with the key
        Throws:
        java.util.ConcurrentModificationException - if it is detected that the remapping function modified this map
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHT);
 return super.merge(key, value, remappingFunction);

      • 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 Hashtable 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 Hashtable) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyHashtable 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 Hashtable-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        entrySet in interface java.util.Map<K,​V>
        Overrides:
        entrySet in class java.util.Hashtable<K,​V>
        Returns:
        a java.util.Set that cannot modify this Hashtable-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableSet(super.entrySet());

      • 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 Hashtable 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 Hashtable) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyHashtable 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 Hashtable-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        keySet in interface java.util.Map<K,​V>
        Overrides:
        keySet in class java.util.Hashtable<K,​V>
        Returns:
        a java.util.Set that cannot modify this Hashtable-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableSet(super.keySet());

      • 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 Hashtable 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 Hashtable) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyHashtable 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 Hashtable-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        values in interface java.util.Map<K,​V>
        Overrides:
        values in class java.util.Hashtable<K,​V>
        Returns:
        a java.util.Collection that cannot modify this Hashtable-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableCollection(super.values());

      • 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 'hashTable'.
        Specified by:
        equals in interface java.util.Map<K,​V>
        Overrides:
        equals in class java.util.Hashtable<K,​V>
        Parameters:
        o - object to be compared for equality with this ROHashtableBuilder instance
        Returns:
        true if the specified Object is equal to this Builder
        Code:
        Exact Method Body:
         if (this == o) return true;
 if (! (o instanceof ROHashtableBuilder)) return false;
 return super.equals((Hashtable) o);

      • clone

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

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