Class ReadOnlyHashMap<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, ReadOnlyMap<K,​V>
    public class ReadOnlyHashMap<K,​V>
extends java.lang.Object
implements ReadOnlyMap<K,​V>, java.io.Serializable
    This class was originally copied from GitHub's Open-JDK Account. It has been heavily modified as all method bodies have been removed; although few changes were applied to the file's Javadoc Commenting. Method and parameter names & types have not been modified whatsoever - although several methods have been eliminated.

    This file contains nothing more than Wrapper-Code which has been placed around the code from the original Open JDK-21 Source-File of the same (or, rather, highly similar) Class-Name. The original JDK Source-File may be viewed on the JDK-21 GitHub public (and, coincidentally, Read-Only) Source-Release 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.
    Immutable Wrapper for java.util.HashMap, found in the "Java Collections Framework".

    Immutable Wrapper Class:
    This data class contains all of the methods that the standard Java class 'HashMap' contains - except those which would directly or indirectly modify / mutate the internal data-structure.

    In order to guarantee that the contents and values of this HashMap remain constant and unchanged, this class retains an internal HashMap, and assigns it the Java modifier 'private' to prevent any outside, unwanted modification. This class' own methods are all trivial, single-line wrappers that invoke the original java.util methods, but leave out any & all wrappers for methods that have the ability to modify, update, remove or insert values into the internal and private HashMap.

    Finally, this class offers a Read Only Guarantee, which is enforced by preventing any instantiation of this class from occuring that would allow outside references of its internal, private HashMap field

    Immutable interface Inheritance-Tree:
    This class implements a variant of the JDK's java.util.* Interface-Stack, all of which have been slightly modified (and renamed to add the prefix 'ReadOnly' to their names). This decision was necessary because many of the support functions inside Java Collection Framework classes have utility / helper methods that retrieve & generate Sub-Maps and Sub-Sets that are linked to the original Collection's, Set's and Map's from whence they were produced.

    These Sub-Map / Sub-Set retrieval methods all sing the same refrain - changes to the returned Map / Set will be reflected into 'this' instance, and vice-versa.

    These Sub-Map's and Sub-Set's would easily (even though 'accidentally') provide a dangerous back-door means for modifying and updating a Collection that is claiming to be Read-Only & Immutable.

    As a result, the decision was made to also port all of the java.util.* interfaces, such as Set, Map, List & Collection, into the Read-Only Collections Framework by renaming them to ReadOnlySet, ReadOnlyMap, & ReadOnlyCollection - and of course to remove / eliminate all Mutator-Methods from those interfaces. This extra step further guarantees the provision that this Data-Class is, truly, Read-Only and un-modifiable.

    Self-Referential ReadOnlyHashMap's
    Though likely uncommon in most typical software projects, it is possible for a HashMap to actually contain a reference to itself. However, in the translation from a standard HashMap to a ReadOnlyHashMap, there is actually no direct and realizable way to preserve any self-referential pointers inside the ReadOnlyHashMap which is being constructed.

    Java's Generic Type-System, generally, makes such references nearly (but not completely) impossible. Unless you have assigned java.lang.Object to the Data-Class' Generic-Type, there is likely no common Ancestor-Type that would inherit both a ReadOnlyHashMap, and the other objects in your data-set.

    As a result, if you happen to pass an instance of data that contains references or pointers to itself, those pointers will not be updated to reference the Read-Only variant of your Data-Structure when that Data-Structure is created. The ReadOnlyHashMap that you get back will simply contain pointers to the original Data-Structure you passed to the constructor of this class!
    See Also:
    Serialized Form


    • Field Summary

       
      Serializable ID
      Modifier and Type Field
      protected static long serialVersionUID

    • Constructor Summary

       
      Construct an Instance using a Runnable / Tuple2 Combination
      Constructor
      ReadOnlyHashMap​(
         Tuple2<K,​V> refHolder,
         Runnable computeNextEntry,
         Float loadFactor,
         Integer sizeIfKnown
      )
      Constructs an instance of ReadOnlyHashMap that has been populated by the Key-Value Pairs left in 'refHolder' by each invocation of the Runnable parameter 'computeNextEntry'.
       
      Iterable Source: Build an Instance
      Constructor
      ReadOnlyHashMap​(
         Iterable<? extends K> keys,
         Function<? super K,​? extends V> valueMapper,
         Predicate<? super K> filter,
         Float loadFactor,
         Integer sizeIfKnown
      )
      Constructs an instance of ReadOnlyHashMap that contains the keys present in parameter 'keys', and values generated by 'valueMapper' - using each of the 'keys' as input.
      ReadOnlyHashMap​(
         Iterable<X> source,
         Tuple2<K,​V> refHolder,
         Consumer<? super X> computeNextEntry,
         Predicate<? super X> filter,
         Float loadFactor,
         Integer sizeIfKnown
      )
      Populates an instance of ReadOnlyHashMap by iterating the input 'source' iterable, and passing each value returned by that Iterator to the 'computeNextEntry' Java Consumer.
       
      Map Source: Build Instance
      Constructor
      ReadOnlyHashMap​(Map<K,​V> map)
      Copies the contents of parameter 'map', and saves saves it, thereby guaranteeing 'this' instance is Read-Only and fully-shielded from outside modification.
      ReadOnlyHashMap​(
         Tuple2<K,​V> refHolder,
         Map<X,​Y> map,
         Consumer<Map.Entry<X,​Y>> mapTranslator,
         Predicate<Map.Entry<X,​Y>> filter,
         Float loadFactor
      )
      If only a small amount of processing needs to be done on the contents of some Java Map, and using an entire Builder-Class seems disproportionately complex - this constructor can convert any Java Map into a ReadOnlyHashMap, using a simple 'mapTranslator'.
       
      Array Source: Build an Instance
      Constructor
      ReadOnlyHashMap​(
         Predicate<?> filter,
         Consumer<?> computeNextEntry,
         Tuple2<K,​V> refHolder,
         Float loadFactor,
         Object primitiveArray
      )
      Retrieves elements from the Java Primitive-Array parameter 'primitiveArray', and subsequently invokes the 'computeNextEntry' processor to populate this ReadOnlyHashMap.
      ReadOnlyHashMap​(
         Tuple2<K,​V> refHolder,
         Consumer<? super X> computeNextEntry,
         Predicate<? super X> filter,
         Float loadFactor,
         X... elements
      )
      Retrieves elements from the VarArgs Generic-Array parameter 'elements', and subsequently invokes the 'computeNextEntry' processor to populate this ReadOnlyHashMap.

    • 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

      • ReadOnlyHashMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashMap​(java.util.Map<K,​V> map)
        Copies the contents of parameter 'map', and saves saves it, thereby guaranteeing 'this' instance is Read-Only and fully-shielded from outside modification.
        Parameters:
        map - The map to be copied into 'this' instance internal and private 'hashMap' field.
        Code:
        Exact Constructor Body:
         fromBuilderOrHashMap = false;

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.hashMap = (map.size() == 0) ? ((HashMap<K, V>) EMPTY_HASH_MAP) : new HashMap<>(map);

      • ReadOnlyHashMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashMap​
            (Tuple2<K,​V> refHolder,
             java.util.Map<X,​Y> map,
             java.util.function.Consumer<java.util.Map.Entry<X,​Y>> mapTranslator,
             java.util.function.Predicate<java.util.Map.Entry<X,​Y>> filter,
             java.lang.Float loadFactor)
        If only a small amount of processing needs to be done on the contents of some Java Map, and using an entire Builder-Class seems disproportionately complex - this constructor can convert any Java Map into a ReadOnlyHashMap, using a simple 'mapTranslator'.
        Type Parameters:
        X - The Key-Type of the User-Provided Map.
        Y - The Value-Type of the User-Provided Map.
        Parameters:
        refHolder - This must a non-null instance of Tuple2. The provided Consumer is just that, a 'Consumer' rather than a 'Function', since the results of each translation must be assigned to the values inside this tuple in order for them to be inserted into this ReadOnlyHashMap.
        map - Any Java Map.
        mapTranslator - A function for mapping the iterated elements of Map-Types 'X' and 'Y', into the actual HashMap's Key-Type 'K', and Value-Type 'V'. The results of this translation must be placed into the fields inside 'refHolder'.

        If this parameter is passed null, this method will throw a NullPointerException.
        filter - An optional filter that can be used to prevent & prohibit any chosen elements from input 'map' from being inserted into 'this' ReadOnlyTreeMap.

        This parameter may be passed null, and if it is, it will be silently ignored, and all entries present inside 'map' will be processed and inserted into 'this'
        loadFactor - the load factor of the HashMap

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        Throws:
        java.lang.NullPointerException - if either parameter 'i' or parameter 'mapTranslator' is passed null.
        java.lang.IllegalArgumentException - if the load factor is nonpositive
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
 Objects.requireNonNull(mapTranslator, ROHelpers.NULL_MSG + "'mapTranslator'");

 fromBuilderOrHashMap = false;

 HashMap<K, V> hashMap = (loadFactor != null)
     ? new HashMap<>(map.size(), loadFactor)
     : new HashMap<>(map.size());

 if (filter != null)

     for (Map.Entry<X, Y> entry : map.entrySet())
     {
         if (! filter.test(entry)) continue;
         mapTranslator.accept(entry);
         hashMap.put(refHolder.a, refHolder.b);
     }

 else

     for (Map.Entry<X, Y> entry : map.entrySet())
     {
         mapTranslator.accept(entry);
         hashMap.put(refHolder.a, refHolder.b);
     }

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.hashMap = (hashMap.size() == 0) ? ((HashMap<K, V>) EMPTY_HASH_MAP) : hashMap;

      • ReadOnlyHashMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashMap​
            (java.lang.Iterable<? extends K> keys,
             java.util.function.Function<? super K,​? extends V> valueMapper,
             java.util.function.Predicate<? super K> filter,
             java.lang.Float loadFactor,
             java.lang.Integer sizeIfKnown)
        Constructs an instance of ReadOnlyHashMap that contains the keys present in parameter 'keys', and values generated by 'valueMapper' - using each of the 'keys' as input.

        Constructor Body:
        It is likely of the highest benefit to simply look at the imported Constructor-Body Code-Snippet below to understand the exact mechanics of how this constructor incorporates data into this ReadOnlyHashMap's internal HashMap.
        Parameters:
        keys - Any Java Iterable instance.
        valueMapper - A user provided function to compute a map value, based on a map key.
        filter - This parameter may be used to filter some elements returned by the input Iterable instance.

        This parameter may be passed null, and if it is, it will be silently ignored. When it is ignored, all elements from the Iterable parameter are processed and inserted.
        loadFactor - the load factor of the HashMap

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        sizeIfKnown - If the number of elements to be inserted is known, this value / size may be provided, here, to parameter 'sizeIfKnown'. This allows the internal HashMap to be adequately sized & initialized at the beginning of this constructor, alleviating the need / overhead of resizing, again, during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the HashMap constructor. When it is more accurate, the Data-Structure operates more efficiently

        If this parameter is passed null, Java's default-initialization value '16' is used.
        Throws:
        java.lang.NullPointerException - if either 'keys' or 'valueMapper' are passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(keys, ROHelpers.NULL_MSG + "'keys'");
 Objects.requireNonNull(valueMapper, ROHelpers.NULL_MSG + "'valueMapper'");

 fromBuilderOrHashMap = false;

 HashMap<K, V> hashMap = new HashMap<>(
     ((sizeIfKnown == null)  ? 16    : sizeIfKnown),
     ((loadFactor == null)   ? 0.75f : loadFactor)
 );

 if (filter == null)
     for (K key : keys)
         hashMap.put(key, valueMapper.apply(key));

 else
     for (K key : keys)
         if (filter.test(key))
             hashMap.put(key, valueMapper.apply(key));

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.hashMap = (hashMap.size() == 0) ? ((HashMap<K, V>) EMPTY_HASH_MAP) : hashMap;

      • ReadOnlyHashMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashMap​(Tuple2<K,​V> refHolder,
                       java.lang.Runnable computeNextEntry,
                       java.lang.Float loadFactor,
                       java.lang.Integer sizeIfKnown)
        Constructs an instance of ReadOnlyHashMap that has been populated by the Key-Value Pairs left in 'refHolder' by each invocation of the Runnable parameter 'computeNextEntry'. Key-Value Pairs are inserted until an invocation of the Runnable leaves null in refHolder.a and refHolder.b

        Constructor Body:
        It is likely of the highest benefit to simply look at the imported Constructor-Body Code-Snippet below to understand the exact mechanics of how this constructor incorporates data into this ReadOnlyHashMap's internal HashMap.
        Parameters:
        refHolder - Any instance of Tuple2 may be passed to this parameter. This reference may not be null, or a NullPointerException will throw immediately.

        This parameter must be used to populate this ReadOnlyHashMap instance.

        The 'computeNextEntry' instance provided to this method, when invoked, should place each Key-Value Pair that it computes into the two fields of this 'refHolder'. After invoking the 'computeNextEntry' consumer, the contents of this Tuple2 are inserted into this ReadOnlyMap instance.

        Please review the Source-Code in the window below. It, hopefully, elucidates how this method retrieves the data to be placed into this ReadOnlyHashMap using this 'refHolder'.
        computeNextEntry - This Runnable instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyHashMap instance. The Lambda-Expression or Method provided to this Runnable must place each Key-Value Pair into the 'refHolder' instance.

        After each insertion that is performed, the logic will check if the Key and Value of Tuple2 instance have been passed null. When both the Key and the Value are null, this Constructor will cease inserting data into this instance internal HashMap, and exit.

        NOTE: It is acceptabe for this Runnable to return multiple values for a single Key. If redundant Keys are placed into the 'refHolder', the old value assigned to the key will be over-written by the latest value. If both a key and a value placed into 'refHolder' are duplicates, both will be reinserted a second time, which doesn't have any effect on the internally stored HashMap.

        Again, for a detailed understanding of how to use this parameter, it is best just to look at the imported Constructor-Body below!
        loadFactor - the load factor of the HashMap

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        sizeIfKnown - If the number of elements to be inserted is known, this value / size may be provided, here, to parameter 'sizeIfKnown'. This allows the internal HashMap to be adequately sized & initialized at the beginning of this constructor, alleviating the need / overhead of resizing, again, during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the HashMap constructor. When it is more accurate, the Data-Structure operates more efficiently

        If this parameter is passed null, Java's default-initialization value '16' is used.
        Throws:
        java.lang.NullPointerException - if either 'refHolder' or 'computeNextEntry' are passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
 Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

 fromBuilderOrHashMap = false;

 HashMap<K, V> hashMap = new HashMap<>(
     ((sizeIfKnown == null)  ? 16    : sizeIfKnown),
     ((loadFactor == null)   ? 0.75f : loadFactor)
 );

 do
 {
     computeNextEntry.run();
     if ((refHolder.a == null) && (refHolder.b == null)) break;
     hashMap.put(refHolder.a, refHolder.b);
 }
 while (true);

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.hashMap = (hashMap.size() == 0) ? ((HashMap<K, V>) EMPTY_HASH_MAP) : hashMap;

      • ReadOnlyHashMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashMap​
            (java.lang.Iterable<X> source,
             Tuple2<K,​V> refHolder,
             java.util.function.Consumer<? super X> computeNextEntry,
             java.util.function.Predicate<? super X> filter,
             java.lang.Float loadFactor,
             java.lang.Integer sizeIfKnown)
        Populates an instance of ReadOnlyHashMap by iterating the input 'source' iterable, and passing each value returned by that Iterator to the 'computeNextEntry' Java Consumer.

        It is the programmer's responsibility to properly place each Key-Value Pair that is intending to be inserted into the final Map instance into the 'refHolder' instance. After each invocation of 'computeNextEntry', this constructor's logic will retrieve the values within 'refHolder.a' and 'refHolder.b' and insert them into this instance internal HashMap.

        Constructor Body:
        It is likely of the highest benefit to simply look at the imported Constructor-Body Code-Snippet below to understand the exact mechanics of how this constructor incorporates data into this ReadOnlyHashMap's internal HashMap.
        Type Parameters:
        X - The type of the elements inside 'source'
        Parameters:
        source - Any Java Iterable instance.
        refHolder - Any instance of Tuple2 may be passed to this parameter. This reference may not be null, or a NullPointerException will throw immediately.

        This parameter must be used to populate this ReadOnlyHashMap instance.

        The 'computeNextEntry' instance provided to this method, when invoked, should place each Key-Value Pair that it computes into the two fields of this 'refHolder'. After invoking the 'computeNextEntry' consumer, the contents of this Tuple2 are inserted into this ReadOnlyMap instance.

        Please review the Source-Code in the window below. It, hopefully, elucidates how this method retrieves the data to be placed into this ReadOnlyHashMap using this 'refHolder'.
        computeNextEntry - This Consumer instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyHashMap instance. The Lambda-Expression or Method provided to this Consumer must place each Key-Value Pair into the 'refHolder' instance.

        Passed as input to this Consumer will simply be the elements from the input 'source' parameter Iterable-instance (which is iterated in this constructor's body).

        NOTE: It is acceptabe for this Consumer to return multiple values for a single Key. If redundant keys are placed into the 'refHolder', the old value assigned to the key will be over-written by the latest value. If both a key and a value placed into 'refHolder' are duplicates, both will be reinserted a second time, which doesn't have any effect on the internally stored HashMap.

        Again, for a detailed understanding of how to use this parameter, it is best just to look at the imported Constructor-Body below!
        filter - This parameter may be used to filter some elements returned by the input Iterable instance.

        This parameter may be passed null, and if it is, it will be silently ignored. When it is ignored, all elements from the Iterable parameter are processed and inserted.
        loadFactor - the load factor of the HashMap

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        sizeIfKnown - If the number of elements to be inserted is known, this value / size may be provided, here, to parameter 'sizeIfKnown'. This allows the internal HashMap to be adequately sized & initialized at the beginning of this constructor, alleviating the need / overhead of resizing, again, during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the HashMap constructor. When it is more accurate, the Data-Structure operates more efficiently

        If this parameter is passed null, Java's default-initialization value '16' is used.
        Throws:
        java.lang.NullPointerException - if either 'refHolder', 'computeNextEntry' or 'source' are passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
 Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

 fromBuilderOrHashMap = false;

 HashMap<K, V> hashMap = new HashMap<>(
     ((sizeIfKnown == null)  ? 16    : sizeIfKnown),
     ((loadFactor == null)   ? 0.75f : loadFactor)
 );

 X x; // temp var
 Iterator<X> iter = source.iterator();

 if (filter == null)

     while (iter.hasNext())
     {
         computeNextEntry.accept(iter.next());
         hashMap.put(refHolder.a, refHolder.b);
     }

 else

     while (iter.hasNext())
         if (filter.test(x = iter.next()))
         {
             computeNextEntry.accept(x);
             hashMap.put(refHolder.a, refHolder.b);
         }

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.hashMap = (hashMap.size() == 0) ? ((HashMap<K, V>) EMPTY_HASH_MAP) : hashMap;

      • ReadOnlyHashMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashMap​
            (Tuple2<K,​V> refHolder,
             java.util.function.Consumer<? super X> computeNextEntry,
             java.util.function.Predicate<? super X> filter,
             java.lang.Float loadFactor,
             X... elements)
        Retrieves elements from the VarArgs Generic-Array parameter 'elements', and subsequently invokes the 'computeNextEntry' processor to populate this ReadOnlyHashMap.
        Type Parameters:
        X - The type of array parameter 'elements'
        Parameters:
        refHolder - Any instance of Tuple2 may be passed to this parameter. This reference may not be null, or a NullPointerException will throw immediately.

        This parameter must be used to populate this ReadOnlyHashMap instance.

        The 'computeNextEntry' instance provided to this method, when invoked, should place each Key-Value Pair that it computes into the two fields of this 'refHolder'. After invoking the 'computeNextEntry' consumer, the contents of this Tuple2 are inserted into this ReadOnlyMap instance.

        Please review the Source-Code in the window below. It, hopefully, elucidates how this method retrieves the data to be placed into this ReadOnlyHashMap using this 'refHolder'.
        computeNextEntry - This Consumer instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyHashMap instance. The Lambda-Expression or Method provided to this Consumer must place each Key-Value Pair into the 'refHolder' instance.

        Passed as input to this Consumer will simply be the elements from the user-provided input-array.

        NOTE: It is acceptabe for this Consumer to return multiple values for a single Key. If redundant keys are placed into the 'refHolder', the old value assigned to the key will be over-written by the latest value. If both a key and a value placed into 'refHolder' are duplicates, both will be reinserted a second time, which doesn't have any effect on the internally stored HashMap.

        Again, for a detailed understanding of how to use this parameter, it is best just to look at the imported Constructor-Body below!
        filter - This parameter may be used to filter elements from the array-instance, preventing them from being inserted into the ReadOnlyHashMap.

        This parameter may be passed null, and if it is, it will be silently ignored. When it is ignored, all elements from the array parameter are processed and inserted.
        loadFactor - the load factor of the HashMap

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        elements - Any Generic VarArgs-Array
        Throws:
        java.lang.ClassCastException - If 'primitiveArray' cannot be cast to a One-Dimensional, Java Primitive-Array.
        java.lang.NullPointerException - if either 'refHolder' or 'computeNextEntry' are passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
 Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

 this.fromBuilderOrHashMap = false;

 HashMap<K, V> hashMap =
     new HashMap<>(elements.length, ((loadFactor == null) ? 0.75f : loadFactor));

 if (filter == null) for (X e : elements)
 {
     computeNextEntry.accept(e);
     hashMap.put(refHolder.a, refHolder.b);
 }

 else for (X x : elements) if (filter.test(x))
 {
     computeNextEntry.accept(x);
     hashMap.put(refHolder.a, refHolder.b);
 }

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.hashMap = (hashMap.size() == 0) ? ((HashMap<K, V>) EMPTY_HASH_MAP) : hashMap;

      • ReadOnlyHashMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashMap​(java.util.function.Predicate<?> filter,
                       java.util.function.Consumer<?> computeNextEntry,
                       Tuple2<K,​V> refHolder,
                       java.lang.Float loadFactor,
                       java.lang.Object primitiveArray)
        Retrieves elements from the Java Primitive-Array parameter 'primitiveArray', and subsequently invokes the 'computeNextEntry' processor to populate this ReadOnlyHashMap.
        Parameters:
        filter - The Java Predicate passed to this parameter must have a test(...) method that can handle input-references of the Java Boxed-Type that corresponds to the Java-Primitive Type used in parameter 'primitiveArray'.

        In English this means, If you have pased an int[]-Array to 'primitiveArray', and would like to filter some of the elements out of your ReadOnlyHashMap, then you should pass a Predicate<java.lang.Integer> to this parameter.

        If you have passed a char[]-Array, then this parameter should be a Predicate<java.lang.Character> - and so on and so forth...

        NOTE: This is, indeed, a Run-Time rather than a Compile-Time Type-Solution. If you would like to know what that means (in plain English), it is as follows: There isn't a way to request that the Java-Compiler ensure, and print error-messages on error, that you have passed a Predicate<Integer> for an int[]-Array and a Predicate<Float> for a float[]-Array.

        If an erroneous Predicate is passed to parameter 'filter', then, during Run-Time, a ClassCastException will throw - rather than having a Compile-Time Error generated.
        computeNextEntry - This Consumer instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyHashMap instance. The Lambda-Expression or Method provided to this Consumer must place each Key-Value Pair into the 'refHolder' instance.

        Passed as input to this Consumer will simply be the elements from the user-provided input-array.

        NOTE: It is acceptabe for this Consumer to return multiple values for a single Key. If redundant keys are placed into the 'refHolder', the old value assigned to the key will be over-written by the latest value. If both a key and a value placed into 'refHolder' are duplicates, both will be reinserted a second time, which doesn't have any effect on the internally stored HashMap.

        Again, for a detailed understanding of how to use this parameter, it is best just to look at the imported Constructor-Body below!
        refHolder - Any instance of Tuple2 may be passed to this parameter. This reference may not be null, or a NullPointerException will throw immediately.

        This parameter must be used to populate this ReadOnlyHashMap instance.

        The 'computeNextEntry' instance provided to this method, when invoked, should place each Key-Value Pair that it computes into the two fields of this 'refHolder'. After invoking the 'computeNextEntry' consumer, the contents of this Tuple2 are inserted into this ReadOnlyMap instance.

        Please review the Source-Code in the window below. It, hopefully, elucidates how this method retrieves the data to be placed into this ReadOnlyHashMap using this 'refHolder'.
        loadFactor - the load factor of the HashMap

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        primitiveArray - Any Java Primitive-Array
        Throws:
        java.lang.ClassCastException - If 'primitiveArray' cannot be cast to a One-Dimensional, Java Primitive-Array.
        java.lang.NullPointerException - if either 'refHolder' or 'computeNextEntry' are passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
 Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

 this.fromBuilderOrHashMap = false;

 HashMap<K, V> hashMap = ROHelpers.buildROMap(
     primitiveArray,
     (int arrayLen) -> new HashMap<>(arrayLen, ((loadFactor == null) ? 0.75f : loadFactor)),
     filter,
     refHolder,
     computeNextEntry
 );

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.hashMap = (hashMap.size() == 0) ? ((HashMap<K, V>) EMPTY_HASH_MAP) : hashMap;

    • Method Detail

      • emptyROHM

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <X,​Y> ReadOnlyHashMap<X,​Y> emptyROHM()
        Returns an empty, singleton, instance of ReadOnlyHashMap.
        Type Parameters:
        X - Returned ReadOnlyMap's Key-Type.
        Y - Returned ReadOnlyMap's Value-Type.
        Returns:
        An empty map. Since this map is both empty & read-only, a raw-type singleton will suffice for all operations offered by this clas.
        Code:
        Exact Method Body:
         return (ReadOnlyHashMap<X, Y>) EMPTY_READONLY_HASH_MAP;

      • cloneToHashMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.HashMap<K,​V> cloneToHashMap()
        Clone's 'this' instance internal HashMap<K, V> field, and returns it. This method generates a Read / Write Cloned Version of 'this' instance' internal ReadOnlyHashMap. The instance that's returned by this method is a clone, and this decision preserves the immutable (Read-Only) protection offered by this class.

        Standard JDK HashMap
        The returned object is a Standard JDK HashMap data-structure (the one from package java.util). It is mutable, but again because it is a clone of 'this' instance's internal HashMap, it is not actually 'linked' to the internal HashMap

        This does mean that changes to the returned HashMap instance will not be reflected to the 'this' ReadOnlyHashMap. They are, in fact, two independent and unlinked copies of the internal data.
        Returns:
        An independent, mutable copy of 'this' instance internal HashMap<K, V> data-structure.
        Code:
        Exact Method Body:
         if (! fromBuilderOrHashMap) return (HashMap<K, V>) this.hashMap.clone();

 HashMap<K, V> ret = new HashMap<K, V>();

 for (Map.Entry<K, V> e :
     ((ROHashMapBuilder<K, V>) this.hashMap)._entrySet(friendClassBadge))

     ret.put(e.getKey(), e.getValue());

 return ret;

      • wrapToImmutableMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map<K,​V> wrapToImmutableMap()
        Invokes java.util.Collections.unmodifiableMap on the internal HashMap.

        Standard JDK Map:
        There may be situations where the Type ReadOnlyHashMap is simply not usable with an API that can't be adapted to accept Type's from the Java-HTML ReadOnly Package. If such a case arises, this method can be used to generate an immutable instance of a JDK-Standard java.util Type, which does not inherit from Torello.Java.ReadOnly

        Class java.util.Collections offers a method that wraps a type into an Unmodifiable-Wrapper that implements the standard java.util.Map, but throws an exception if any attempts are made to invoke Mutator-Methods.

        Unmodifiable-Collections throw Exceptions instead:
        The returned java.util.Map instance will hopefully provide an acceptable substitute when ReadOnly Type's cannot match an API's requirements. Java's Immutable-Wrappers work on a different principle - these classes retain any / all Mutator-Methods amongst their Type-Members, but instead throw an UnsupportedOperationException if any of those methods are invoked!

        Also, if a Java Collections Framework Unmodifiable-Class has any Member-Methods that return a "View" into the underlying Data-Structure, the Sub-Lists and Sub-Maps returned by those methods are also, subsequently, wrapped in an Unmodifiable-Wrapper. These returned instances will also throw an UnsupportedOperationException if any of those methods are invoked!

        This does provide a shield or layer of protection against modification to guarantee the "Immutability-Contract" offered by these classes, all-the-while returning to native Java API Collection Types, rather than Torello.Java.ReadOnly Types, which may not always be compatible with a given API or Interface requirement!

        Remember, many of the Data-Classes inside java.util have methods whose documentation state very clearly that "any changes made the this [View] will be pushed back into the original type."
        Returns:
        A Map which adheres to the JDK interface java.util.Map, but throws an UnsupportedOperationException if a user attempts to invoke a Mutator-Method on the returned instance.
        Code:
        Exact Method Body:
         return Collections.unmodifiableMap(this.hashMap);

      • size

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int size()
        Returns the number of key-value mappings in this map.
        Specified by:
        size in interface ReadOnlyMap<K,​V>
        Returns:
        the number of key-value mappings in this map
        Code:
        Exact Method Body:
         return this.hashMap.size();

      • isEmpty

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean isEmpty()
        Returns TRUE if this map contains no key-value mappings.
        Specified by:
        isEmpty in interface ReadOnlyMap<K,​V>
        Returns:
        TRUE if this map contains no key-value mappings
        Code:
        Exact Method Body:
         return this.hashMap.isEmpty();

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V get​(java.lang.Object key)
        Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.

        More formally, if this map contains a mapping from a key k to a value v such that (key==null ? k==null : key.equals(k)), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

        A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.
        Specified by:
        get in interface ReadOnlyMap<K,​V>
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        the value to which the specified key is mapped, or null if this map contains no mapping for the key
        Code:
        Exact Method Body:
         return this.hashMap.get(key);

      • containsKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean containsKey​(java.lang.Object key)
        Returns TRUE if this map contains a mapping for the specified key.
        Specified by:
        containsKey in interface ReadOnlyMap<K,​V>
        Parameters:
        key - The key whose presence in this map is to be tested
        Returns:
        TRUE if this map contains a mapping for the specified key.
        Code:
        Exact Method Body:
         return this.hashMap.containsKey(key);

      • containsValue

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean containsValue​(java.lang.Object value)
        Returns TRUE if this map maps one or more keys to the specified value.
        Specified by:
        containsValue in interface ReadOnlyMap<K,​V>
        Parameters:
        value - value whose presence in this map is to be tested
        Returns:
        TRUE if this map maps one or more keys to the specified value
        Code:
        Exact Method Body:
         return this.hashMap.containsValue(value);

      • keySet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlySet<K> keySet()
        Returns a ReadOnlySet view of the keys contained in this map.
        Specified by:
        keySet in interface ReadOnlyMap<K,​V>
        Returns:
        a set view of the keys contained in this map
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlySet(
     fromBuilderOrHashMap
         ? ((ROHashMapBuilder<K, V>) this.hashMap)._keySet(friendClassBadge)
         : this.hashMap.keySet()
 );

      • values

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyCollection<V> values()
        Returns a ReadOnlyCollection view of the values contained in this map.
        Specified by:
        values in interface ReadOnlyMap<K,​V>
        Returns:
        a view of the values contained in this map
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlyCollection(
     fromBuilderOrHashMap
         ? ((ROHashMapBuilder<K, V>) this.hashMap)._values(friendClassBadge)
         : this.hashMap.values()
 );

      • getOrDefault

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V getOrDefault​(java.lang.Object key,
                      V defaultValue)
        Description copied from interface: ReadOnlyMap
        Returns the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key.
        Specified by:
        getOrDefault in interface ReadOnlyMap<K,​V>
        Parameters:
        key - the key whose associated value is to be returned
        defaultValue - the default mapping of the key
        Returns:
        the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key
        Code:
        Exact Method Body:
         return this.hashMap.getOrDefault(key, defaultValue);

      • forEach

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void forEach​
            (java.util.function.BiConsumer<? super K,​? super V> action)
        Description copied from interface: ReadOnlyMap
        Performs the given action for each entry in this map until all entries have been processed or the action throws an exception. Unless otherwise specified by the implementing class, actions are performed in the order of entry set iteration (if an iteration order is specified.) Exceptions thrown by the action are relayed to the caller.

        The default implementation is equivalent to, for this map: 

         for (ReadOnlyMap.Entry<K, V> entry : map.entrySet())
     action.accept(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.
        Specified by:
        forEach in interface ReadOnlyMap<K,​V>
        Parameters:
        action - The action to be performed for each entry
        Code:
        Exact Method Body:
         this.hashMap.forEach(action);

      • toString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Returns a String representation of this map. The String representation consists of a list of key-value mappings in the order returned by the map's entrySet view's iterator, enclosed in braces ("{}"). Adjacent mappings are separated by the characters ", " (comma and space). Each key-value mapping is rendered as the key followed by an equals sign ("=") followed by the associated value. Keys and values are converted to String's as by String.valueOf(Object).
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of this HashMap
        Code:
        Exact Method Body:
         return ROHelpers.toString(
     this.hashMap, // if the map contains itself, it is needed for printing purposes
     fromBuilderOrHashMap
         ? ((ROHashMapBuilder<K, V>) this.hashMap)._entrySet(friendClassBadge)
         : this.hashMap.entrySet()
 );

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object o)
        Compares the specified Object with this Map for equality, as per the definition in the class java.util.HashMap.
        Specified by:
        equals in interface ReadOnlyMap<K,​V>
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - object to be compared for equality with this ReadOnlyHashMap.
        Returns:
        TRUE if the specified Object is equal to this Map
        Code:
        Exact Method Body:
         return ROHelpers.roMapEq(this, o);