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

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

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

      • Nested classes/interfaces inherited from interface java.util.Map

        java.util.Map.Entry<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
      ROHashMapBuilder()
      Constructs an empty ROHashMapBuilder with the default initial capacity (16) and the default load factor (0.75).
      ROHashMapBuilder​(int initialCapacity)
      Constructs an empty ROHashMapBuilder with the specified initial capacity and the default load factor (0.75).
      ROHashMapBuilder​(int initialCapacity, float loadFactor)
      Constructs an empty ROHashMapBuilder with the specified initial capacity and load factor.
      ROHashMapBuilder​(Map<? extends K,​? extends V> m)
      Constructs a new ROHashMapBuilder with the same mappings as the specified Map.

    • Method Summary

       
      Convert this Builder into a ReadOnlyHashMap instance
      Modifier and Type Method
      ReadOnlyHashMap<K,​V> build()
      Simply transfers 'this' instance' internal HashMap to the ReadOnlyHashMap 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> m)
      Copies all of the mappings from the specified map to this map.
      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-Map Builder
      Modifier and Type Method
      void clear()
      Removes all of the mappings from this map.
      V remove​(Object key)
      Removes the mapping for the specified key from this map if present.
      boolean remove​(Object key, Object value)
      Removes the entry for the specified key only if it is currently mapped to the specified 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)
      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 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.
       
      Static-Factory Builder
      Modifier and Type Method
      static <K,​V>
      ROHashMapBuilder<K,​V>      		 newROHashMapBuilder​(int numMappings)
      Creates a new, empty ROHashMapBuilder suitable for the expected number of mappings.
       
      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 original class HashMap.
       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method
      ROHashMapBuilder<K,​V> clone()
      Clones this instance' of ROHashMapBuilder.

      • Methods inherited from class java.util.HashMap

        containsKey, containsValue, forEach, get, getOrDefault, isEmpty, size

      • Methods inherited from class java.util.AbstractMap

        hashCode, toString

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.util.Map

        hashCode

    • 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

      • ROHashMapBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashMapBuilder​(int initialCapacity,
                        float loadFactor)
        Constructs an empty ROHashMapBuilder with the specified initial capacity and load factor.

        To create a ROHashMapBuilder with an initial capacity that accommodates an expected number of mappings, use newROHashMapBuilder.
        Parameters:
        initialCapacity - the initial capacity
        loadFactor - the load factor
        Throws:
        java.lang.IllegalArgumentException - if the initial capacity is negative or the load factor is nonpositive
        Code:
        Exact Constructor Body:
         super(initialCapacity, loadFactor);

      • ROHashMapBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashMapBuilder​(int initialCapacity)
        Constructs an empty ROHashMapBuilder with the specified initial capacity and the default load factor (0.75).

        To create a ROHashMapBuilder with an initial capacity that accommodates an expected number of mappings, use newROHashMapBuilder.
        Parameters:
        initialCapacity - the initial capacity.
        Throws:
        java.lang.IllegalArgumentException - if the initial capacity is negative.
        Code:
        Exact Constructor Body:
         super(initialCapacity);

      • ROHashMapBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashMapBuilder​(java.util.Map<? extends K,​? extends V> m)
        Constructs a new ROHashMapBuilder with the same mappings as the specified Map. The ROHashMapBuilder is created with default load factor (0.75) and an initial capacity sufficient to hold the mappings in the specified Map.
        Parameters:
        m - 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:
         super(m);

    • Method Detail

      • build

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

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

      • newROHashMapBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <K,​V> ROHashMapBuilder<K,​V> newROHashMapBuilder​
            (int numMappings)
        Creates a new, empty ROHashMapBuilder suitable for the expected number of mappings. The returned map uses the default load factor of 0.75, and its initial capacity is generally large enough so that the expected number of mappings can be added without resizing the map.
        Type Parameters:
        K - the type of keys maintained by the new map
        V - the type of mapped values
        Parameters:
        numMappings - the expected number of mappings
        Returns:
        the newly created map
        Throws:
        java.lang.IllegalArgumentException - if numMappings is negative
        Code:
        Exact Method Body:
         if (numMappings < 0)
     throw new IllegalArgumentException("Negative number of mappings: " + numMappings);

 return new ROHashMapBuilder<>(calculateHashMapCapacity(numMappings));

      • 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 HashMap. Note that any method which modifies this internal HashMap 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.HashMap<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.)
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHM);
 return super.put(key, value);

      • putAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void putAll​(java.util.Map<? extends K,​? extends V> m)
        Copies all of the mappings from the specified map to this map. These mappings will 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 HashMap. Note that any method which modifies this internal HashMap 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.HashMap<K,​V>
        Parameters:
        m - 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(ROHM);
 super.putAll(m);

      • remove

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

        Mutator Method:
        This method modifies the contents of this class' internal HashMap. Note that any method which modifies this internal HashMap 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.HashMap<K,​V>
        Parameters:
        key - key whose mapping is to be removed from the map
        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.)
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHM);
 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 HashMap. Note that any method which modifies this internal HashMap 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.HashMap<K,​V>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHM);
 super.clear();

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


        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 HashMap. Note that any method which modifies this internal HashMap 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.HashMap<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.UnsupportedOperationException - if the put operation is not supported by this map
        java.lang.ClassCastException - if the key or value is of an inappropriate type for this map
        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(ROHM);
 return super.putIfAbsent(key, value);

      • remove

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean remove​(java.lang.Object key,
                      java.lang.Object value)
        Removes the entry for the specified key only if it is currently mapped to the specified value.

        The default implementation is equivalent to, for this map: 

         if (map.containsKey(key) && Objects.equals(map.get(key), value))
 {
     map.remove(key);
     return true;
 }
 
 return false;


        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 HashMap. Note that any method which modifies this internal HashMap 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.HashMap<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 removed
        Throws:
        java.lang.UnsupportedOperationException - if the remove operation is not supported by this map
        java.lang.ClassCastException - if the key or value is of an inappropriate type for this map
        java.lang.NullPointerException - if the specified key or value is null, and this map does not permit null keys or values
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHM);
 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;
 }
 
 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.

        Mutator Method:
        This method modifies the contents of this class' internal HashMap. Note that any method which modifies this internal HashMap 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.HashMap<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.UnsupportedOperationException - if the put operation is not supported by this map
        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
        java.lang.NullPointerException - if oldValue is null and this map does not permit null values
        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(ROHM);
 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);
 return 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 HashMap. Note that any method which modifies this internal HashMap 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.HashMap<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.UnsupportedOperationException - if the put operation is not supported by this map
        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, 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(ROHM);
 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 it is detected that the mapping function modifies this map during computation.

        Mutator Method:
        This method modifies the contents of this class' internal HashMap. Note that any method which modifies this internal HashMap 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.HashMap<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(ROHM);
 return super.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 it is detected that the remapping function modifies this map during computation.

        Mutator Method:
        This method modifies the contents of this class' internal HashMap. Note that any method which modifies this internal HashMap 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.HashMap<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(ROHM);
 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 it is detected that the remapping function modifies this map during computation.

        Mutator Method:
        This method modifies the contents of this class' internal HashMap. Note that any method which modifies this internal HashMap 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.HashMap<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(ROHM);
 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)


        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 it is detected that the remapping function modifies this map during computation.

        Mutator Method:
        This method modifies the contents of this class' internal HashMap. Note that any method which modifies this internal HashMap 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.HashMap<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
        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(ROHM);
 return super.merge(key, value, remappingFunction);

      • 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 implementation is equivalent to: 

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


        No guarantees about synchronization or atomicity properties of this method.

        Mutator Method:
        This method modifies the contents of this class' internal HashMap. Note that any method which modifies this internal HashMap 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.HashMap<K,​V>
        Parameters:
        function - the function to apply to each entry
        Throws:
        java.lang.UnsupportedOperationException - if the set operation is not supported by this map's entry set iterator.
        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(ROHM);
 super.replaceAll(function);

      • 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 HashMap 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 HashMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyHashMap 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 HashMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        entrySet in interface java.util.Map<K,​V>
        Overrides:
        entrySet in class java.util.HashMap<K,​V>
        Returns:
        a java.util.Set that cannot modify this HashMap-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 HashMap 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 HashMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyHashMap 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 HashMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        keySet in interface java.util.Map<K,​V>
        Overrides:
        keySet in class java.util.HashMap<K,​V>
        Returns:
        a java.util.Set that cannot modify this HashMap-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 HashMap 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 HashMap) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyHashMap 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 HashMap-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        values in interface java.util.Map<K,​V>
        Overrides:
        values in class java.util.HashMap<K,​V>
        Returns:
        a java.util.Collection that cannot modify this HashMap-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 original class java.util.HashMap. Ignores the private field 'built'. If 'this' has not been built, but 'o' has been, that fact is ignored during the equality-comparison.
        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 ROHashMapBuilder instance
        Returns:
        true if the specified Object is equal to this Builder
        Code:
        Exact Method Body:
         if (this == o) return true;
 if (! (o instanceof ROHashMapBuilder)) return false;
 return super.equals((HashMap) o);

      • clone

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

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