Class ReadOnlyHashtable<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, ReadOnlyDictionary<K,​V>, ReadOnlyMap<K,​V>
    Direct Known Subclasses:
    ReadOnlyProperties
    public class ReadOnlyHashtable<K,​V>
extends java.lang.Object
implements ReadOnlyDictionary<K,​V>, ReadOnlyMap<K,​V>, java.lang.Cloneable, 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.Hashtable, found in the "Java Collections Framework".

    Immutable Wrapper Class:
    This data class contains all of the methods that the standard Java class 'Hashtable' 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 Hashtable remain constant and unchanged, this class retains an internal Hashtable, 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 Hashtable.

    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 Hashtable 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 ReadOnlyHashtable's
    Though likely uncommon in most typical software projects, it is possible for a Hashtable to actually contain a reference to itself. However, in the translation from a standard Hashtable to a ReadOnlyHashtable, there is actually no direct and realizable way to preserve any self-referential pointers inside the ReadOnlyHashtable 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 ReadOnlyHashtable, 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 ReadOnlyHashtable that you get back will simply contain pointers to the original Data-Structure you passed to the constructor of this class!

    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 a Multi-Threaded-Friendly Type.

    Because this Wrapper-Class is simply incapable of data-writes itself, Thread-Safe Synchronization is therefore totally irrelevant. As a result, none of the methods in this class are declared 'synchronized', and the concept is completely ignored.

    Do we need Vector & Hashtable at all?
    The Java Collections Framework provides one Thread-Safe List in java.util.Vector, and one Map through java.util.Hashtable. Each of the methods in both of these classes are adorned with the 'synchronized' keyword, meaning their functions are atomic with respect to invocations, by other threads, on the same instance of a class.

    Given that this package is about creating Read-Only Classes, and since such a class is, by definition, Thread-Safe - why should we even need a ReadOnlyVector or a ReadOnlyHashtable? Well, since the Builder's for both of these classes also 'synchronized', it was decided that these two should stick around. The other reason is simply that some people (like me, for instance) are so used to typing 'Vector' that switching to 'ArrayList' would sort of be unthinkable!

    Remember that the builder's for all of these Read-Only Collections cannot be immutable / Read-Only (otherwise how would data be inserted into them?), so it seems to be important enough to retain these two 'synchronized' variants after all - even though Read-Only classes are, by definition, Thread-Safe.
    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
      ReadOnlyHashtable​(
         Tuple2<K,​V> refHolder,
         Runnable computeNextEntry,
         Float loadFactor,
         Integer sizeIfKnown
      )
      Constructs an instance of ReadOnlyHashtable 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
      ReadOnlyHashtable​(
         Iterable<? extends K> keys,
         Function<? super K,​? extends V> valueMapper,
         Predicate<? super K> filter,
         Float loadFactor,
         Integer sizeIfKnown
      )
      Constructs an instance of ReadOnlyHashtable that contains the keys present in parameter 'keys', and values generated by 'valueMapper' - using each of the 'keys' as input.
      ReadOnlyHashtable​(
         Iterable<X> source,
         Tuple2<K,​V> refHolder,
         Consumer<? super X> computeNextEntry,
         Predicate<? super X> filter,
         Float loadFactor,
         Integer sizeIfKnown
      )
      Populates an instance of ReadOnlyHashtable by iterating the input 'source' iterable, and passing each value returned by that Iterator to the 'computeNextEntry' Java Consumer.
       
      Map Source: Build Instance
      Constructor
      ReadOnlyHashtable​(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.
      ReadOnlyHashtable​(
         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 ReadOnlyHashtable, using a simple 'mapTranslator'.
       
      Array Source: Build an Instance
      Constructor
      ReadOnlyHashtable​(
         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 ReadOnlyHashtable.
      ReadOnlyHashtable​(
         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 ReadOnlyHashtable.

    • 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

      • ReadOnlyHashtable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashtable​(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 'hashTable' field.
        Code:
        Exact Constructor Body:
         this.fromBuilderOrHashtable = false;

 this.hashTable = (map.size() == 0)
     ? ((Hashtable<K, V>) EMPTY_HASH_TABLE)
     : new Hashtable<>(map);

      • ReadOnlyHashtable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashtable​
            (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 ReadOnlyHashtable, 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 ReadOnlyHashtable.
        map - Any Java Map.
        mapTranslator - A consumer for mapping the iterated elements of Map-Types 'X' and 'Y', into the actual Hashtable'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 Hashtable

        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.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
 Objects.requireNonNull(mapTranslator, ROHelpers.NULL_MSG + "'mapTranslator'");

 fromBuilderOrHashtable = false;

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

 if (filter == null)

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

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

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

      • ReadOnlyHashtable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashtable​
            (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 ReadOnlyHashtable 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 ReadOnlyHashtable's internal Hashtable.
        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 Hashtable

        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 Hashtable 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 Hashtable 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'");

 fromBuilderOrHashtable = false;

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

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

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

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

      • ReadOnlyHashtable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashtable​(Tuple2<K,​V> refHolder,
                         java.lang.Runnable computeNextEntry,
                         java.lang.Float loadFactor,
                         java.lang.Integer sizeIfKnown)
        Constructs an instance of ReadOnlyHashtable 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 ReadOnlyHashtable's internal Hashtable.
        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 ReadOnlyHashtable 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 ReadOnlyHashtable using this 'refHolder'.
        computeNextEntry - This Runnable instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyHashtable 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 Hashtable, 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 Hashtable.

        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 Hashtable

        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 Hashtable 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 Hashtable 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'");

 fromBuilderOrHashtable = false;

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

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

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

      • ReadOnlyHashtable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashtable​
            (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 ReadOnlyHashtable 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 Hashtable.

        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 ReadOnlyHashtable's internal Hashtable.
        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 ReadOnlyHashtable 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 ReadOnlyHashtable using this 'refHolder'.
        computeNextEntry - This Consumer instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyHashtable 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 Hashtable.

        Again, for a detailed understanding of how to use this parameter, it is best just to look at the imported Constructor-Body below!
        filter - May be used to filter out some of the elements of 'source'
        loadFactor - the load factor of the Hashtable

        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 Hashtable 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 Hashtable 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'");

 fromBuilderOrHashtable = false;

 Hashtable<K, V> hashTable = new Hashtable<>(
     ((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());
         hashTable.put(refHolder.a, refHolder.b);
     }

 else

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

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

      • ReadOnlyHashtable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashtable​
            (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 ReadOnlyHashtable.
        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 ReadOnlyHashtable 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 ReadOnlyHashtable using this 'refHolder'.
        computeNextEntry - This Consumer instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyHashtable 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 Hashtable.

        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 ReadOnlyHashtable.

        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 Hashtable

        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.fromBuilderOrHashtable = false;

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

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

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

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

      • ReadOnlyHashtable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashtable​(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 ReadOnlyHashtable.
        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 ReadOnlyHashtable, 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 ReadOnlyHashtable 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 Hashtable.

        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 ReadOnlyHashtable 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 ReadOnlyHashtable using this 'refHolder'.
        loadFactor - the load factor of the Hashtable

        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.fromBuilderOrHashtable = false;

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

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

    • Method Detail

      • emptyROHT

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <X,​Y> ReadOnlyHashtable<X,​Y> emptyROHT()
        Returns an empty, singleton, instance of ReadOnlyHashtable.
        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 (ReadOnlyHashtable<X, Y>) EMPTY_READONLY_HASH_TABLE;

      • cloneToHashtable

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Hashtable<K,​V> cloneToHashtable()
        Clone's 'this' instance internal Hashtable<K, V> field, and returns it. This method generates a Read / Write Cloned Version of 'this' instance' internal ReadOnlyHashtable. 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 Hashtable
        The returned object is a Standard JDK Hashtable data-structure (the one from package java.util). It is mutable, but again because it is a clone of 'this' instance's internal Hashtable, it is not actually 'linked' to the internal Hashtable

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

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

 for (Map.Entry<K, V> e :
     ((ROHashtableBuilder<K, V>) this.hashTable)._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 Hashtable.

        Standard JDK Map:
        There may be situations where the Type ReadOnlyHashtable 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.hashTable);

      • keys

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Enumeration<K> keys()
        Returns an enumeration of the keys in this Hashtable. Use the Enumeration methods on the returned object to fetch the keys sequentially.
        Specified by:
        keys in interface ReadOnlyDictionary<K,​V>
        Returns:
        an enumeration of the keys in this Hashtable.
        See Also:
        elements(), keySet(), ReadOnlyMap
        Code:
        Exact Method Body:
         return this.hashTable.keys();

      • elements

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Enumeration<V> elements()
        Returns an enumeration of the values in this Hashtable. Use the Enumeration methods on the returned object to fetch the elements sequentially.
        Specified by:
        elements in interface ReadOnlyDictionary<K,​V>
        Returns:
        an enumeration of the values in this Hashtable.
        See Also:
        keys(), values(), ReadOnlyMap
        Code:
        Exact Method Body:
         return this.hashTable.elements();

      • contains

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean contains​(java.lang.Object value)
        Tests if some key maps into the specified value in this Hashtable. This operation is more expensive than the containsKey method.

        Note that this method is identical in functionality to containsValue, (which is part of the ReadOnlyMap interface.
        Parameters:
        value - a value to search for
        Returns:
        TRUE if and only if some key maps to the value argument in this Hashtable as determined by the equals method; false otherwise.
        Throws:
        java.lang.NullPointerException - if the value is null
        Code:
        Exact Method Body:
         return this.hashTable.contains(value);

      • containsValue

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean containsValue​(java.lang.Object value)
        Returns TRUE if this Hashtable maps one or more keys to this value.

        Note that this method is identical in functionality to contains(java.lang.Object).
        Specified by:
        containsValue in interface ReadOnlyMap<K,​V>
        Parameters:
        value - value whose presence in this Hashtable is to be tested
        Returns:
        TRUE if this map maps one or more keys to the specified value
        Throws:
        java.lang.NullPointerException - if the value is null
        Code:
        Exact Method Body:
         return this.hashTable.contains(value);

      • containsKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean containsKey​(java.lang.Object key)
        Tests if the specified object is a key in this Hashtable.
        Specified by:
        containsKey in interface ReadOnlyMap<K,​V>
        Parameters:
        key - possible key
        Returns:
        TRUE if and only if the specified object is a key in this Hashtable, as determined by the equals method; false otherwise.
        Throws:
        java.lang.NullPointerException - if the key is null
        See Also:
        contains(Object)
        Code:
        Exact Method Body:
         return this.hashTable.containsKey(key);

      • 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.equals(k)), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)
        Specified by:
        get in interface ReadOnlyDictionary<K,​V>
        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
        Throws:
        java.lang.NullPointerException - if the specified key is null
        Code:
        Exact Method Body:
         return this.hashTable.get(key);

      • keySet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlySet<K> keySet()
        Returns a ReadOnlySet view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa.
        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(
     fromBuilderOrHashtable
         ? ((ROHashtableBuilder<K, V>) this.hashTable)._keySet(friendClassBadge)
         : this.hashTable.keySet()
 );

      • entrySet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlySet<ReadOnlyMap.Entry<K,​V>> entrySet()
        Returns a ReadOnlySet view of the mappings contained in this map.
        Specified by:
        entrySet in interface ReadOnlyMap<K,​V>
        Returns:
        a set view of the mappings contained in this map
        Code:
        Exact Method Body:
         return ROHelpers.toReadOnlyEntrySet(
     fromBuilderOrHashtable
         ? ((ROHashtableBuilder<K, V>) this.hashTable)._entrySet(friendClassBadge)
         : this.hashTable.entrySet()
 );

      • 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 collection view of the values contained in this map
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlyCollection(
     fromBuilderOrHashtable
         ? ((ROHashtableBuilder<K, V>) this.hashTable)._values(friendClassBadge)
         : this.hashTable.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.hashTable.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.hashTable.forEach(action);

      • toString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Returns a string representation of this Hashtable object in the form of a set of entries, enclosed in braces and separated by the ASCII characters " , " (comma and space). Each entry is rendered as the key, an equals sign '=', and the associated element, where the toString method is used to convert the key and element to String's.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of this Hashtable
        Code:
        Exact Method Body:
         return ROHelpers.toString(
     this.hashTable, // if the map contains itself, it is needed for printing purposes
     fromBuilderOrHashtable
         ? ((ROHashtableBuilder<K, V>) this.hashTable)._entrySet(friendClassBadge)
         : this.hashTable.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.Hashtable.
        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 ReadOnlyHashtable.
        Returns:
        TRUE if the specified Object is equal to this Map
        Code:
        Exact Method Body:
         return ROHelpers.roMapEq(this, o);