Class ROVectorBuilder<E>

  • Type Parameters:
    E - Type of component elements
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.List<E>, java.util.RandomAccess
    public final class ROVectorBuilder<E>
extends java.util.Vector<E>
implements java.util.RandomAccess, 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 Vector class; used for building a ReadOnlyVector. Maintains an internal and inaccessible Vector<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.

    Synchronized Class Wrapper:
    This class is a Wrapper-Class for an internal, private Vector 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.Vector to see it is Multi-Threaded-Friendly Type.

    This class maintains no internal data of its own (whatsoever!) This Wrapper-Class' methods, therefore, have not been declared using the 'sychronized' keyword. Adding the 'synchronized' modifier to these methods would be superfluous, and have no effect at all other than to cause a reduction in performance.

    Another way of saying this is that every single method in this class simply turns around and calls a method from java.util.Vector which is, itself, completely synchronized already. Thusly, these methods, here, don't need a second round of synchronization added.
    See Also:
    ReadOnlyVector, Serialized Form


    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static long serialVersionUID

      • Fields inherited from class java.util.Vector

        capacityIncrement, elementCount, elementData

      • Fields inherited from class java.util.AbstractList

        modCount

    • Constructor Summary

      Constructors 
      Constructor Description
      ROVectorBuilder()
      Constructs an empty vector so that its internal data array has size 10 and its standard capacity increment is zero.
      ROVectorBuilder​(int initialCapacity)
      Constructs an empty vector with the specified initial capacity and with its capacity increment equal to zero.
      ROVectorBuilder​(int initialCapacity, int capacityIncrement)
      Constructs an empty vector with the specified initial capacity and capacity increment.
      ROVectorBuilder​(Collection<? extends E> c)
      Constructs a vector containing the elements of the specified collection, in the order they are returned by the collection's iterator.

    • Method Summary

       
      Convert this Builder into a ReadOnly Vector instance
      Modifier and Type Method
      ReadOnlyVector<E> build()
      Simply transfers 'this' instance' internal Vector to the ReadOnlyVector Wrapper-Class.
       
      Add Items to this Read-Only-List Builder
      Modifier and Type Method
      void add​(int index, E element)
      Inserts the specified element at the specified position in this Vector.
      boolean add​(E e)
      Appends the specified element to the end of this Vector.
      boolean addAll​(int index, Collection<? extends E> c)
      Inserts all of the elements in the specified Collection into this Vector at the specified position.
      boolean addAll​(Collection<? extends E> c)
      Appends all of the elements in the specified Collection to the end of this Vector, in the order that they are returned by the specified Collection's Iterator.
      void addElement​(E obj)
      Adds the specified component to the end of this vector, increasing its size by one.
      void insertElementAt​(E obj, int index)
      Inserts the specified object as a component in this vector at the specified index.
       
      Remove Items from this Read-Only-List Builder
      Modifier and Type Method
      void clear()
      Removes all of the elements from this Vector.
      E remove​(int index)
      Removes the element at the specified position in this Vector.
      boolean remove​(Object o)
      Removes the first occurrence of the specified element in this Vector If the Vector does not contain the element, it is unchanged.
      boolean removeAll​(Collection<?> c)
      Removes from this Vector all of its elements that are contained in the specified Collection.
      void removeAllElements()
      Removes all components from this vector and sets its size to zero.
      boolean removeElement​(Object obj)
      Removes the first (lowest-indexed) occurrence of the argument from this vector.
      void removeElementAt​(int index)
      Deletes the component at the specified index.
      boolean removeIf​(Predicate<? super E> filter)
      Removes all of the elements of this collection that satisfy the given predicate.
      boolean retainAll​(Collection<?> c)
      Retains only the elements in this Vector that are contained in the specified Collection.
       
      Replace List-Builder Items
      Modifier and Type Method
      void replaceAll​(UnaryOperator<E> operator)
      Replaces each element of this list with the result of applying the operator to that element.
      E set​(int index, E element)
      Replaces the element at the specified position in this Vector with the specified element.
      void setElementAt​(E obj, int index)
      Sets the component at the specified index of this vector to be the specified object.
       
      JDK Standard Vector Methods
      Modifier and Type Method
      void ensureCapacity​(int minCapacity)
      Increases the capacity of this vector, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.
      void setSize​(int newSize)
      Sets the size of this vector.
      void sort​(Comparator<? super E> c)
      Sorts this list according to the order induced by the specified Comparator.
      void trimToSize()
      Trims the capacity of this vector to be the vector's current size.
       
      Mutable / Read-Write View Generators - Return Instances with Unmodifiable-Wrappers
      Modifier and Type Method
      ListIterator<E> listIterator()
      Restricted-Access Instance
      ListIterator<E> listIterator​(int index)
      Restricted-Access Instance
      List<E> subList​(int fromIndex, int toIndex)
      Restricted-Access Instance
       
      Methods: class java.lang.Object
      Modifier and Type Method
      boolean equals​(Object o)
      Compares the specified Object with this Builder for equality, as per the definition in the private and internal field 'vector'.
       
      Methods: interface java.lang.Iterable
      Modifier and Type Method
      RemoveUnsupportedIterator<E> iterator()
      Restricted-Access Instance
       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method
      ROVectorBuilder<E> clone()
      Clones this instance' of ROVectorBuilder.

      • Methods inherited from class java.util.Vector

        capacity, contains, containsAll, copyInto, elementAt, elements, firstElement, forEach, get, hashCode, indexOf, indexOf, isEmpty, lastElement, lastIndexOf, lastIndexOf, removeRange, size, spliterator, 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

    • 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

      • ROVectorBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROVectorBuilder​(int initialCapacity,
                       int capacityIncrement)
        Constructs an empty vector with the specified initial capacity and capacity increment.
        Parameters:
        initialCapacity - the initial capacity of the vector
        capacityIncrement - the amount by which the capacity is increased when the vector overflows
        Throws:
        java.lang.IllegalArgumentException - if the specified initial capacity is negative
        Code:
        Exact Constructor Body:
         super(initialCapacity, capacityIncrement);

      • ROVectorBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROVectorBuilder​(int initialCapacity)
        Constructs an empty vector with the specified initial capacity and with its capacity increment equal to zero.
        Parameters:
        initialCapacity - the initial capacity of the vector
        Throws:
        java.lang.IllegalArgumentException - if the specified initial capacity is negative
        Code:
        Exact Constructor Body:
         super(initialCapacity);

      • ROVectorBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROVectorBuilder​(java.util.Collection<? extends E> c)
        Constructs a vector containing the elements of the specified collection, in the order they are returned by the collection's iterator.
        Parameters:
        c - the collection whose elements are to be placed into this vector
        Throws:
        java.lang.NullPointerException - if the specified collection is null
        Code:
        Exact Constructor Body:
         super(c);

    • Method Detail

      • build

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

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

      • trimToSize

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void trimToSize()
        Trims the capacity of this vector to be the vector's current size. If the capacity of this vector is larger than its current size, then the capacity is changed to equal the size by replacing its internal data array, kept in the field elementData, with a smaller one. An application can use this operation to minimize the storage of a vector.

        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().
        Overrides:
        trimToSize in class java.util.Vector<E>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.trimToSize();

      • ensureCapacity

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void ensureCapacity​(int minCapacity)
        Increases the capacity of this vector, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.

        If the current capacity of this vector is less than minCapacity, then its capacity is increased by replacing its internal data array, kept in the field elementData, with a larger one. The size of the new data array will be the old size plus capacityIncrement, unless the value of capacityIncrement is less than or equal to zero, in which case the new capacity will be twice the old capacity; but if this new size is still smaller than minCapacity, then the new capacity will be minCapacity.

        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().
        Overrides:
        ensureCapacity in class java.util.Vector<E>
        Parameters:
        minCapacity - the desired minimum capacity
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.ensureCapacity(minCapacity);

      • setSize

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setSize​(int newSize)
        Sets the size of this vector. If the new size is greater than the current size, new null items are added to the end of the vector. If the new size is less than the current size, all components at index newSize and greater are discarded.

        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().
        Overrides:
        setSize in class java.util.Vector<E>
        Parameters:
        newSize - the new size of this vector
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the new size is negative
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.setSize(newSize);

      • setElementAt

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setElementAt​(E obj,
                         int index)
        Sets the component at the specified index of this vector to be the specified object. The previous component at that position is discarded.

        The index must be a value greater than or equal to 0 and less than the current size of the vector.

        This method is identical in functionality to the set(int, E) method (which is part of the ReadOnlyList interface). Note that the set method reverses the order of the parameters, to more closely match array usage. Note also that the set method returns the old value that was stored at the specified position.

        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().
        Overrides:
        setElementAt in class java.util.Vector<E>
        Parameters:
        obj - what the component is to be set to
        index - the specified index
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.setElementAt(obj, index);

      • removeElementAt

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void removeElementAt​(int index)
        Deletes the component at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted downward to have an index one smaller than the value it had previously. The size of this vector is decreased by 1.

        The index must be a value greater than or equal to 0 and less than the current size of the vector.

        This method is identical in functionality to the remove(int) method (which is part of the ReadOnlyList interface). Note that the remove method returns the old value that was stored at the specified position.

        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().
        Overrides:
        removeElementAt in class java.util.Vector<E>
        Parameters:
        index - the index of the object to remove
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.removeElementAt(index);

      • insertElementAt

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void insertElementAt​(E obj,
                            int index)
        Inserts the specified object as a component in this vector at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

        The index must be a value greater than or equal to 0 and less than or equal to the current size of the vector. (If the index is equal to the current size of the vector, the new element is appended to the Vector.)

        This method is identical in functionality to the add(int, E) method (which is part of the ReadOnlyList interface). Note that the add method reverses the order of the parameters, to more closely match array usage.

        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().
        Overrides:
        insertElementAt in class java.util.Vector<E>
        Parameters:
        obj - the component to insert
        index - where to insert the new component
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the index is out of range (index < 0 || index > size())
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.insertElementAt(obj, index);

      • addElement

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void addElement​(E obj)
        Adds the specified component to the end of this vector, increasing its size by one. The capacity of this vector is increased if its size becomes greater than its capacity.

        This method is identical in functionality to the add(E) method (which is part of the ReadOnlyList interface).

        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().
        Overrides:
        addElement in class java.util.Vector<E>
        Parameters:
        obj - the component to be added
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.addElement(obj);

      • removeElement

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean removeElement​(java.lang.Object obj)
        Removes the first (lowest-indexed) occurrence of the argument from this vector. If the object is found in this vector, each component in the vector with an index greater or equal to the object's index is shifted downward to have an index one smaller than the value it had previously.

        This method is identical in functionality to the remove(Object) method (which is part of the ReadOnlyList interface).

        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().
        Overrides:
        removeElement in class java.util.Vector<E>
        Parameters:
        obj - the component to be removed
        Returns:
        TRUE if the argument was a component of this vector; FALSE otherwise.
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 return super.removeElement(obj);

      • removeAllElements

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void removeAllElements()
        Removes all components from this vector and sets its size to zero.

        This method is identical in functionality to the clear() method (which is part of the ReadOnlyList interface).

        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().
        Overrides:
        removeAllElements in class java.util.Vector<E>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.removeAllElements();

      • set

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E set​(int index,
             E element)
        Replaces the element at the specified position in this Vector with the specified element.

        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:
        set in interface java.util.List<E>
        Overrides:
        set in class java.util.Vector<E>
        Parameters:
        index - index of the element to replace
        element - element to be stored at the specified position
        Returns:
        the element previously at the specified position
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 return super.set(index, element);

      • add

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean add​(E e)
        Appends the specified element to the end of this Vector.

        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.List<E>
        Overrides:
        add in class java.util.Vector<E>
        Parameters:
        e - element to be appended to this Vector
        Returns:
        TRUE (as specified by Collection.add)
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 return super.add(e);

      • remove

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean remove​(java.lang.Object o)
        Removes the first occurrence of the specified element in this Vector If the Vector does not contain the element, it is unchanged. More formally, removes the element with the lowest index i such that Objects.equals(o, get(i)) (if such an element exists).

        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.List<E>
        Overrides:
        remove in class java.util.Vector<E>
        Parameters:
        o - element to be removed from this Vector, if present
        Returns:
        true if the Vector contained the specified element
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 return super.remove(o);

      • add

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void add​(int index,
                E element)
        Inserts the specified element at the specified position in this Vector. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

        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.List<E>
        Overrides:
        add in class java.util.Vector<E>
        Parameters:
        index - index at which the specified element is to be inserted
        element - element to be inserted
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the index is out of range (index < 0 || index > size())
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.add(index, element);

      • remove

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E remove​(int index)
        Removes the element at the specified position in this Vector. Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the Vector.

        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.List<E>
        Overrides:
        remove in class java.util.Vector<E>
        Parameters:
        index - the index of the element to be removed
        Returns:
        element that was removed
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 return super.remove(index);

      • clear

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void clear()
        Removes all of the elements from this Vector. The Vector will be empty after this call returns (unless it throws an exception).

        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.List<E>
        Overrides:
        clear in class java.util.Vector<E>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.clear();

      • addAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean addAll​(java.util.Collection<? extends E> c)
        Appends all of the elements in the specified Collection to the end of this Vector, in the order that they are returned by the specified Collection's Iterator. The behavior of this operation is undefined if the specified Collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified Collection is this Vector, and this Vector is nonempty.)

        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.List<E>
        Overrides:
        addAll in class java.util.Vector<E>
        Parameters:
        c - elements to be inserted into this Vector
        Returns:
        TRUE if this Vector changed as a result of the call
        Throws:
        java.lang.NullPointerException - if the specified collection is null
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 return super.addAll(c);

      • removeAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean removeAll​(java.util.Collection<?> c)
        Removes from this Vector all of its elements that are contained in the specified Collection.

        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:
        removeAll in interface java.util.Collection<E>
        Specified by:
        removeAll in interface java.util.List<E>
        Overrides:
        removeAll in class java.util.Vector<E>
        Parameters:
        c - a collection of elements to be removed from the Vector
        Returns:
        true if this Vector changed as a result of the call
        Throws:
        java.lang.ClassCastException - if the types of one or more elements in this vector are incompatible with the specified collection (optional)
        java.lang.NullPointerException - if this vector contains one or more null elements and the specified collection does not support null elements (optional), or if the specified collection is null
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 return super.removeAll(c);

      • retainAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean retainAll​(java.util.Collection<?> c)
        Retains only the elements in this Vector that are contained in the specified Collection. In other words, removes from this Vector all of its elements that are not contained in the specified Collection.

        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:
        retainAll in interface java.util.Collection<E>
        Specified by:
        retainAll in interface java.util.List<E>
        Overrides:
        retainAll in class java.util.Vector<E>
        Parameters:
        c - a collection of elements to be retained in this Vector (all other elements are removed)
        Returns:
        true if this Vector changed as a result of the call
        Throws:
        java.lang.ClassCastException - if the types of one or more elements in this vector are incompatible with the specified collection (optional)
        java.lang.NullPointerException - if this vector contains one or more null elements and the specified collection does not support null elements (optional), or if the specified collection is null
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 return super.retainAll(c);

      • removeIf

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean removeIf​(java.util.function.Predicate<? super E> filter)
        Removes all of the elements of this collection that satisfy the given predicate. Errors or runtime exceptions thrown during iteration or by the predicate are relayed to the caller.

        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:
        removeIf in interface java.util.Collection<E>
        Overrides:
        removeIf in class java.util.Vector<E>
        Parameters:
        filter - a Predicate which returns TRUE for elements to be removed
        Returns:
        TRUE if any elements were removed
        Throws:
        java.lang.NullPointerException - if the specified filter is null
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 return super.removeIf(filter);

      • addAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean addAll​(int index,
                      java.util.Collection<? extends E> c)
        Inserts all of the elements in the specified Collection into this Vector at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in the Vector in the order that they are returned by the specified Collection's iterator.

        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.List<E>
        Overrides:
        addAll in class java.util.Vector<E>
        Parameters:
        index - index at which to insert the first element from the specified collection
        c - elements to be inserted into this Vector
        Returns:
        TRUE if this Vector changed as a result of the call
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the index is out of range (index < 0 || index > size())
        java.lang.NullPointerException - if the specified collection is null
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 return super.addAll(index, c);

      • replaceAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void replaceAll​(java.util.function.UnaryOperator<E> operator)
        Replaces each element of this list with the result of applying the operator to that element. Errors or runtime exceptions thrown by the operator are relayed to the caller.

        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:
        replaceAll in interface java.util.List<E>
        Overrides:
        replaceAll in class java.util.Vector<E>
        Parameters:
        operator - the operator to apply to each element
        Throws:
        java.lang.NullPointerException - if the specified operator is null or if the operator result is a null value and this list does not permit null elements (optional)
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.replaceAll(operator);

      • sort

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void sort​(java.util.Comparator<? super E> c)
        Sorts this list according to the order induced by the specified Comparator. The sort is stable: this method must not reorder equal elements.

        All elements in this list must be mutually comparable using the specified comparator (that is, c.compare(e1, e2) must not throw a ClassCastException for any elements e1 and e2 in the list).

        If the specified comparator is null then all elements in this list must implement the Comparable interface and the elements' natural ordering should be used.

        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:
        sort in interface java.util.List<E>
        Overrides:
        sort in class java.util.Vector<E>
        Parameters:
        c - the Comparator used to compare list elements. A null value indicates that the elements' natural ordering should be used
        Throws:
        java.lang.ClassCastException - if the list contains elements that are not mutually comparable using the specified comparator
        java.lang.IllegalArgumentException - if the comparator is found to violate the Comparator contract
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROV);
 super.sort(c);

      • 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 Iterator 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 Iterator (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.List<E>
        Overrides:
        iterator in class java.util.Vector<E>
        Returns:
        a java.util.Iterator that cannot modify this Vector-Builder
        Code:
        Exact Method Body:
         return new RemoveUnsupportedIterator<>(super.iterator());

      • listIterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.ListIterator<E> listIterator()
        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 ListIterator 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 ListIterator (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:
        listIterator in interface java.util.List<E>
        Overrides:
        listIterator in class java.util.Vector<E>
        Returns:
        a java.util.ListIterator that cannot modify this Vector-Builder
        Code:
        Exact Method Body:
         return ROHelpers.removeUnsupportedListIterator(super.listIterator());

      • listIterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.ListIterator<E> listIterator​(int index)
        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 ListIterator 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 ListIterator (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:
        listIterator in interface java.util.List<E>
        Overrides:
        listIterator in class java.util.Vector<E>
        Returns:
        a java.util.ListIterator that cannot modify this Vector-Builder
        Code:
        Exact Method Body:
         return ROHelpers.removeUnsupportedListIterator(super.listIterator(index));

      • subList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.List<E> subList​(int fromIndex,
                                 int toIndex)
        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 List 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 List (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:
        subList in interface java.util.List<E>
        Overrides:
        subList in class java.util.Vector<E>
        Returns:
        a java.util.List that cannot modify this Vector-Builder
        Code:
        Exact Method Body:
         return Collections.unmodifiableList(super.subList(fromIndex, toIndex));

      • 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 'vector'.
        Specified by:
        equals in interface java.util.Collection<E>
        Specified by:
        equals in interface java.util.List<E>
        Overrides:
        equals in class java.util.Vector<E>
        Parameters:
        o - object to be compared for equality with this ROVectorBuilder instance
        Returns:
        true if the specified Object is equal to this Builder
        Code:
        Exact Method Body:
         if (this == o) return true;
 if (! (o instanceof ROVectorBuilder)) return false;
 return super.equals((ROVectorBuilder) o);

      • clone

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

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