Class ROTreeSetBuilder<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.NavigableSet<E>, java.util.Set<E>, java.util.SortedSet<E>
    public final class ROTreeSetBuilder<E>
extends java.util.TreeSet<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 TreeSet class; used for building a ReadOnlyTreeSet. Maintains an internal and inaccessible TreeSet<E> instance. Upon build completion, this instance is passed to the ReadOnlyVector 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 ReadOnlyVector 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 Vector 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 ReadOnlyVector 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.Vector (explained further, below), making it extremely easy to use.

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

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


    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static long serialVersionUID

    • Constructor Summary

      Constructors 
      Constructor Description
      ROTreeSetBuilder()
      Constructs a new, empty tree set, sorted according to the natural ordering of its elements.
      ROTreeSetBuilder​(Collection<? extends E> c)
      Constructs a new tree set containing the elements in the specified collection, sorted according to the natural ordering of its elements.
      ROTreeSetBuilder​(Comparator<? super E> comparator)
      Constructs a new, empty tree set, sorted according to the specified comparator.
      ROTreeSetBuilder​(SortedSet<E> s)
      Constructs a new tree set containing the same elements and using the same ordering as the specified sorted set.

    • Method Summary

       
      Convert this Builder into a ReadOnlyTreeSet Instance
      Modifier and Type Method Description
      ReadOnlyTreeSet<E> build()
      Simply transfers 'this' instance' internal TreeSet to the ReadOnlyTreeSet Wrapper-Class.
       
      Add Items to this Read-Only-Set Builder
      Modifier and Type Method Description
      boolean add​(E e)
      Adds the specified element to this set if it is not already present.
      boolean addAll​(Collection<? extends E> c)
      Adds all of the elements in the specified collection to this set.
       
      Remove Items from this Read-Only-Set Builder
      Modifier and Type Method Description
      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)  
       
      Poll (Remove & Return) Set Elements
      Modifier and Type Method Description
      E pollFirst()
      Retrieves and removes the first (lowest) element, or returns null if this set is empty.
      E pollLast()
      Retrieves and removes the last (highest) element, or returns null if this set is empty.
       
      Mutable / Read-Write View Generators - Return Instances with Unmodifiable-Wrappers
      Modifier and Type Method Description
      NavigableSet<E> descendingSet()
      Restricted-Access Instance
      SortedSet<E> headSet​(E toElement)
      Restricted-Access Instance
      NavigableSet<E> headSet​(E toElement, boolean inclusive)
      Restricted-Access Instance
      NavigableSet<E> subSet​(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive)
      Restricted-Access Instance
      SortedSet<E> subSet​(E fromElement, E toElement)
      Restricted-Access Instance
      SortedSet<E> tailSet​(E fromElement)
      Restricted-Access Instance
      NavigableSet<E> tailSet​(E fromElement, boolean inclusive)
      Restricted-Access Instance
       
      Methods: class java.lang.Object
      Modifier and Type Method Description
      boolean equals​(Object o)
      Compares the specified Object with this Builder for equality, as per the definition in the private and internal field 'treeSet'.
       
      Methods: interface java.lang.Iterable
      Modifier and Type Method Description
      RemoveUnsupportedIterator<E> descendingIterator()
      Restricted-Access Instance
      RemoveUnsupportedIterator<E> iterator()
      Restricted-Access Instance
       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method Description
      ROTreeSetBuilder<E> clone()
      Clones this instance' of ROTreeSetBuilder.

      • Methods inherited from class java.util.TreeSet

        ceiling, comparator, contains, first, floor, higher, isEmpty, last, lower, 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

      • ROTreeSetBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROTreeSetBuilder()
        Constructs a new, empty tree set, sorted according to the natural ordering of its elements. All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set. If the user attempts to add an element to the set that violates this constraint (for example, the user attempts to add a string element to a set whose elements are integers), the add call will throw a ClassCastException.
        Code:
        Exact Constructor Body:
         super();

      • ROTreeSetBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROTreeSetBuilder​(java.util.Comparator<? super E> comparator)
        Constructs a new, empty tree set, sorted according to the specified comparator. All elements inserted into the set must be mutually comparable by the specified comparator: comparator.compare(e1, e2) must not throw a ClassCastException for any elements e1 and e2 in the set. If the user attempts to add an element to the set that violates this constraint, the add call will throw a ClassCastException.
        Parameters:
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        Code:
        Exact Constructor Body:
         super(comparator);

      • ROTreeSetBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROTreeSetBuilder​(java.util.Collection<? extends E> c)
        Constructs a new tree set containing the elements in the specified collection, sorted according to the natural ordering of its elements. All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        c - collection whose elements will comprise the new set
        Throws:
        java.lang.ClassCastException - if the elements in c are not Comparable, or are not mutually comparable
        java.lang.NullPointerException - if the specified collection is null
        Code:
        Exact Constructor Body:
         super(c);

      • ROTreeSetBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROTreeSetBuilder​(java.util.SortedSet<E> s)
        Constructs a new tree set containing the same elements and using the same ordering as the specified sorted set.
        Parameters:
        s - sorted set whose elements will comprise the new set
        Throws:
        java.lang.NullPointerException - if the specified sorted set is null
        Code:
        Exact Constructor Body:
         super(s);

    • Method Detail

      • build

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

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

      • iterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public RemoveUnsupportedIterator<E> iterator()
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned xx in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying Vector that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this xx (which possesses methods for mutating the Vector) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyVector that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this Vector-Builder will, instead, throw a Java UnsupportedOperationException.
        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.NavigableSet<E>
        Specified by:
        iterator in interface java.util.Set<E>
        Overrides:
        iterator in class java.util.TreeSet<E>
        Returns:
        a java.util.Iterator that cannot modify this Vector-Builder
        Code:
        Exact Method Body:
         return new RemoveUnsupportedIterator<>(super.iterator());

      • descendingIterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public RemoveUnsupportedIterator<E> descendingIterator()
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned xx in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying Vector that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this xx (which possesses methods for mutating the Vector) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyVector that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this Vector-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        descendingIterator in interface java.util.NavigableSet<E>
        Overrides:
        descendingIterator in class java.util.TreeSet<E>
        Returns:
        a java.util.Iterator that cannot modify this Vector-Builder
        Code:
        Exact Method Body:
         return new RemoveUnsupportedIterator<>(super.descendingIterator());

      • 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 the 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 TreeMap. Note that any method which modifies this internal TreeMap 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.TreeSet<E>
        Parameters:
        e - element to be added to this set
        Returns:
        TRUE if this set did not already contain the specified element
        Throws:
        java.lang.ClassCastException - if the specified object cannot be compared with the elements currently in this set
        java.lang.NullPointerException - if the specified element is null and this set uses natural ordering, or its comparator does not permit null elements
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTS);
 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 TreeMap. Note that any method which modifies this internal TreeMap 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.TreeSet<E>
        Parameters:
        o - object to be removed from this set, if present
        Returns:
        TRUE if this set contained the specified element
        Throws:
        java.lang.ClassCastException - if the specified object cannot be compared with the elements currently in this set
        java.lang.NullPointerException - if the specified element is null and this set uses natural ordering, or its comparator does not permit null elements
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTS);
 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 TreeMap. Note that any method which modifies this internal TreeMap 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.TreeSet<E>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTS);
 super.clear();

      • addAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean addAll​(java.util.Collection<? extends E> c)
        Adds all of the elements in the specified collection to this set.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        addAll in interface java.util.Collection<E>
        Specified by:
        addAll in interface java.util.Set<E>
        Overrides:
        addAll in class java.util.TreeSet<E>
        Parameters:
        c - collection containing elements to be added to this set
        Returns:
        TRUE if this set changed as a result of the call
        Throws:
        java.lang.ClassCastException - if the elements provided cannot be compared with the elements currently in the set
        java.lang.NullPointerException - if the specified collection is null or if any element is null and this set uses natural ordering, or its comparator does not permit null elements
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTS);
 return super.addAll(c);

      • pollFirst

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E pollFirst()
        Retrieves and removes the first (lowest) element, or returns null if this set is empty.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        pollFirst in interface java.util.NavigableSet<E>
        Overrides:
        pollFirst in class java.util.TreeSet<E>
        Returns:
        the first element, or null if this set is empty
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTS);
 return super.pollFirst();

      • pollLast

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E pollLast()
        Retrieves and removes the last (highest) element, or returns null if this set is empty.

        Mutator Method:
        This method modifies the contents of this class' internal TreeMap. Note that any method which modifies this internal TreeMap field will throw an exception if invoked after a call to build().
        Specified by:
        pollLast in interface java.util.NavigableSet<E>
        Overrides:
        pollLast in class java.util.TreeSet<E>
        Returns:
        the last element, or null if this set is empty
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROTS);
 return super.pollLast();

      • descendingSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.NavigableSet<E> descendingSet()
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned NavigableSet in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying Vector that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this NavigableSet (which possesses methods for mutating the Vector) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyVector that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this Vector-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        descendingSet in interface java.util.NavigableSet<E>
        Overrides:
        descendingSet in class java.util.TreeSet<E>
        Returns:
        a java.util.NavigableSet that cannot modify this TreeSet-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableNavigableSet(super.descendingSet());

      • headSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.SortedSet<E> headSet​(E toElement)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned SortedSet in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying Vector that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this SortedSet (which possesses methods for mutating the Vector) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyVector that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this Vector-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        headSet in interface java.util.NavigableSet<E>
        Specified by:
        headSet in interface java.util.SortedSet<E>
        Overrides:
        headSet in class java.util.TreeSet<E>
        Returns:
        a java.util.SortedSet that cannot modify this TreeSet-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableSortedSet(super.headSet(toElement, false));

      • headSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.NavigableSet<E> headSet​(E toElement,
                                         boolean inclusive)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned NavigableSet in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying Vector that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this NavigableSet (which possesses methods for mutating the Vector) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyVector that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this Vector-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        headSet in interface java.util.NavigableSet<E>
        Overrides:
        headSet in class java.util.TreeSet<E>
        Returns:
        a java.util.NavigableSet that cannot modify this TreeSet-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableNavigableSet(super.headSet(toElement, inclusive));

      • subSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.NavigableSet<E> subSet​(E fromElement,
                                        boolean fromInclusive,
                                        E toElement,
                                        boolean toInclusive)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned NavigableSet in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying Vector that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this NavigableSet (which possesses methods for mutating the Vector) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyVector that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this Vector-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        subSet in interface java.util.NavigableSet<E>
        Overrides:
        subSet in class java.util.TreeSet<E>
        Returns:
        a java.util.NavigableSet that cannot modify this TreeSet-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableNavigableSet
     (super.subSet(fromElement, fromInclusive, toElement, toInclusive));

      • subSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.SortedSet<E> subSet​(E fromElement,
                                     E toElement)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned SortedSet in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying Vector that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this SortedSet (which possesses methods for mutating the Vector) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyVector that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this Vector-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        subSet in interface java.util.NavigableSet<E>
        Specified by:
        subSet in interface java.util.SortedSet<E>
        Overrides:
        subSet in class java.util.TreeSet<E>
        Returns:
        a java.util.SortedSet that cannot modify this TreeSet-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableSortedSet
     (super.subSet(fromElement, true, toElement, false));

      • tailSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.NavigableSet<E> tailSet​(E fromElement,
                                         boolean inclusive)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned NavigableSet in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying Vector that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this NavigableSet (which possesses methods for mutating the Vector) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyVector that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this Vector-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        tailSet in interface java.util.NavigableSet<E>
        Overrides:
        tailSet in class java.util.TreeSet<E>
        Returns:
        a java.util.NavigableSet that cannot modify this TreeSet-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableNavigableSet(super.tailSet(fromElement, inclusive));

      • tailSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.SortedSet<E> tailSet​(E fromElement)
        Restricts a back-door into the underlying data-structure.

        UnsupportedOperationException Specifics:
        This method invokes the Java Standard Collections class static-method for 'wrapping' this method's returned SortedSet in an Immutable-Wrapper. Java's Collections Framework Immutable-Wrappers have been around since prior to JDK 8, and are easy to use. The wrapper utilized here is needed because this particular method returns a Read-Write "View" into the underlying Vector that facilitates modifying data inside this class' instances.

        Once 'this' builder instance has been built into a Read-Only Data-Structure, this SortedSet (which possesses methods for mutating the Vector) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyVector that is ultimately built.

        Remember that all sub-sets and sub-maps returned by the Java Collections Framework guarantee that any changes to the sub-set or sub-map will be reflected and translated back into the original Collection from whence they were created.

        The returned instance is usable, but any method that would modify this Vector-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        tailSet in interface java.util.NavigableSet<E>
        Specified by:
        tailSet in interface java.util.SortedSet<E>
        Overrides:
        tailSet in class java.util.TreeSet<E>
        Returns:
        a java.util.SortedSet that cannot modify this TreeSet-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableSortedSet(super.tailSet(fromElement, true));

      • 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(ROTS);
 return super.removeAll(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(ROTS);
 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(ROTS);
 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 private and internal field 'treeSet'.
        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 ROTreeSetBuilder instance
        Returns:
        true if the specified Object is equal to this Builder
        Code:
        Exact Method Body:
         if (this == o) return true;
 if (! (o instanceof ROTreeSetBuilder)) return false;
 return super.equals((TreeSet) o);

      • clone

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

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