Class ROHashSetBuilder<E>

  • Type Parameters:
    E - the type of elements maintained by this set
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.Set<E>
    public final class ROHashSetBuilder<E>
extends java.util.HashSet<E>
implements java.lang.Cloneable, java.io.Serializable
    This class was originally copied from GitHub's Open-JDK Account. Though the original file has been modified, few changes were applied to the Javadoc Commenting. Method and parameter names & types have not been modified whatsoever. This file may be viewed on the GitHub Archive for Java Package java.util.*

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

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

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

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

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

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

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

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

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

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

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

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


    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static long serialVersionUID

    • Constructor Summary

      Constructors 
      Constructor Description
      ROHashSetBuilder()
      Constructs a new, empty ROHashSetBuilder, the underlying HashMap instance has default initial capacity (16) and load factor (0.75).
      ROHashSetBuilder​(int initialCapacity)
      Constructs a new, empty ROHashSetBuilder; the backing HashMap instance has the specified initial capacity and default load factor (0.75).
      ROHashSetBuilder​(int initialCapacity, float loadFactor)
      Constructs a new, empty ROHashSetBuilder; the backing HashMap instance has the specified initial capacity and the specified load factor.
      ROHashSetBuilder​(Collection<? extends E> c)
      Constructs a new ROHashSetBuilder containing the elements in the specified collection.

    • Method Summary

       
      Convert this Builder into a ReadOnlyHashSet instance
      Modifier and Type Method
      ReadOnlyHashSet<E> build()
      Simply transfers 'this' instance' internal HashSet to the ReadOnlyHashSet Wrapper-Class.
       
      Add Items to this Read-Only-Set Builder
      Modifier and Type Method
      boolean add​(E e)
      Adds the specified element to this set if it is not already present.
      boolean addAll​(Collection<? extends E> c)  
       
      Remove Items from this Read-Only-Set Builder
      Modifier and Type Method
      void clear()
      Removes all of the elements from this set.
      boolean remove​(Object o)
      Removes the specified element from this set if it is present.
      boolean removeAll​(Collection<?> c)  
      boolean removeIf​(Predicate<? super E> filter)  
      boolean retainAll​(Collection<?> c)  
       
      Static-Factory Builder
      Modifier and Type Method
      static <T> ROHashSetBuilder<T> newROHashSetBuilder​(int numElements)
      Creates a new, empty ROHashSetBuilder suitable for the expected number of elements.
       
      Methods: class java.lang.Object
      Modifier and Type Method
      boolean equals​(Object o)
      Compares the specified Object with this Builder for equality, as per the definition in the original class HashSet.
       
      Methods: interface java.lang.Iterable
      Modifier and Type Method
      RemoveUnsupportedIterator<E> iterator()  
       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method
      ROHashSetBuilder<E> clone()
      Clones this instance' of ROHashSetBuilder.

      • Methods inherited from class java.util.HashSet

        contains, isEmpty, size, spliterator

      • Methods inherited from class java.util.AbstractSet

        hashCode

      • Methods inherited from class java.util.AbstractCollection

        containsAll, toArray, toArray, toString

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.util.Collection

        parallelStream, stream, toArray

      • Methods inherited from interface java.lang.Iterable

        forEach

      • Methods inherited from interface java.util.Set

        containsAll, hashCode, toArray, toArray

    • 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

      • ROHashSetBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashSetBuilder()
        Constructs a new, empty ROHashSetBuilder, the underlying HashMap instance has default initial capacity (16) and load factor (0.75).

      • ROHashSetBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashSetBuilder​(java.util.Collection<? extends E> c)
        Constructs a new ROHashSetBuilder containing the elements in the specified collection. The underlying HashMap is created with default load factor (0.75) and an initial capacity sufficient to contain the elements in the specified collection.
        Parameters:
        c - the collection whose elements are to be placed into this set
        Throws:
        java.lang.NullPointerException - if the specified collection is null
        Code:
        Exact Constructor Body:
         super(c);

      • ROHashSetBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashSetBuilder​(int initialCapacity,
                        float loadFactor)
        Constructs a new, empty ROHashSetBuilder; the backing HashMap instance has the specified initial capacity and the specified load factor.

        To create a ROHashSetBuilder with an initial capacity that accommodates an expected number of elements, use newROHashSetBuilder.
        Parameters:
        initialCapacity - the initial capacity of the hash map
        loadFactor - the load factor of the hash map
        Throws:
        java.lang.IllegalArgumentException - if the initial capacity is less than zero, or if the load factor is nonpositive
        Code:
        Exact Constructor Body:
         super(initialCapacity, loadFactor);

      • ROHashSetBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashSetBuilder​(int initialCapacity)
        Constructs a new, empty ROHashSetBuilder; the backing HashMap instance has the specified initial capacity and default load factor (0.75).

        To create a ReadOnlyHashSet with an initial capacity that accommodates an expected number of elements, use newROHashSetBuilder.
        Parameters:
        initialCapacity - the initial capacity of the hash table
        Throws:
        java.lang.IllegalArgumentException - if the initial capacity is less than zero
        Code:
        Exact Constructor Body:
         super(initialCapacity);

    • Method Detail

      • build

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

 return (size() == 0)
     ? ReadOnlyHashSet.emptyROHS()
     : new ReadOnlyHashSet<E>(this, friendClassBadge);

      • newROHashSetBuilder

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

 return new ROHashSetBuilder<>(calculateHashMapCapacity(numElements));

      • iterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public RemoveUnsupportedIterator<E> iterator()
        Specified by:
        iterator in interface java.util.Collection<E>
        Specified by:
        iterator in interface java.lang.Iterable<E>
        Specified by:
        iterator in interface java.util.Set<E>
        Overrides:
        iterator in class java.util.HashSet<E>
        Code:
        Exact Method Body:
         return new RemoveUnsupportedIterator<>(super.iterator());

      • add

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean add​(E e)
        Adds the specified element to this set if it is not already present. More formally, adds the specified element e to this set if this set contains no element e2 such that Objects.equals(e, e2). If this set already contains the element, the call leaves the set unchanged and returns FALSE.

        Mutator Method:
        This method modifies the contents of this class' internal HashSet. Note that any method which modifies this internal HashSet field will throw an exception if invoked after a call to build().
        Specified by:
        add in interface java.util.Collection<E>
        Specified by:
        add in interface java.util.Set<E>
        Overrides:
        add in class java.util.HashSet<E>
        Parameters:
        e - element to be added to this set
        Returns:
        TRUE if this set did not already contain the specified element
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHS);
 return super.add(e);

      • remove

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean remove​(java.lang.Object o)
        Removes the specified element from this set if it is present. More formally, removes an element e such that Objects.equals(o, e), if this set contains such an element. Returns TRUE if this set contained the element (or equivalently, if this set changed as a result of the call). (This set will not contain the element once the call returns.)

        Mutator Method:
        This method modifies the contents of this class' internal HashSet. Note that any method which modifies this internal HashSet field will throw an exception if invoked after a call to build().
        Specified by:
        remove in interface java.util.Collection<E>
        Specified by:
        remove in interface java.util.Set<E>
        Overrides:
        remove in class java.util.HashSet<E>
        Parameters:
        o - object to be removed from this set, if present
        Returns:
        TRUE if the set contained the specified element
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHS);
 return super.remove(o);

      • clear

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

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

      • removeAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean removeAll​(java.util.Collection<?> c)
        Specified by:
        removeAll in interface java.util.Collection<E>
        Specified by:
        removeAll in interface java.util.Set<E>
        Overrides:
        removeAll in class java.util.AbstractSet<E>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHS);
 return super.removeAll(c);

      • addAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean addAll​(java.util.Collection<? extends E> c)
        Specified by:
        addAll in interface java.util.Collection<E>
        Specified by:
        addAll in interface java.util.Set<E>
        Overrides:
        addAll in class java.util.AbstractCollection<E>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHS);
 return super.addAll(c);

      • retainAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean retainAll​(java.util.Collection<?> c)
        Specified by:
        retainAll in interface java.util.Collection<E>
        Specified by:
        retainAll in interface java.util.Set<E>
        Overrides:
        retainAll in class java.util.AbstractCollection<E>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHS);
 return super.retainAll(c);

      • removeIf

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean removeIf​(java.util.function.Predicate<? super E> filter)
        Specified by:
        removeIf in interface java.util.Collection<E>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROHS);
 return super.removeIf(filter);

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object o)
        Compares the specified Object with this Builder for equality, as per the definition in the original class java.util.HashSet. Ignores the private field 'built'. If 'this' has not been built, but 'o' has been, that fact is ignored during the equality-comparison.
        Specified by:
        equals in interface java.util.Collection<E>
        Specified by:
        equals in interface java.util.Set<E>
        Overrides:
        equals in class java.util.AbstractSet<E>
        Parameters:
        o - object to be compared for equality with this ROHashSetBuilder instance
        Returns:
        true if the specified Object is equal to this Builder
        Code:
        Exact Method Body:
         if (this == o) return true;
 if (! (o instanceof ROHashSetBuilder)) return false;
 return super.equals((HashSet) o);

      • clone

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public ROHashSetBuilder<E> clone()
        Clones this instance' of ROHashSetBuilder.

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