/*
 * Copyright (c) 1994, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package Torello.Java.ReadOnly;

import java.io.Serializable;

import java.util.function.Predicate;
import java.util.function.UnaryOperator;

import Torello.Java.Additional.RemoveUnsupportedIterator;

import java.util.*;

/**
 * A Copy of Java's {@code Vector} class; used for building a {@link ReadOnlyVector}.
 * Maintains <I>an internal and inaccessible {@code Vector<E>} instance</I>. 
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=Vector>
 * <EMBED CLASS='external-html' DATA-A_AN=a DATA-FILE-ID=BUILDERS>
 * <EMBED CLASS='external-html' DATA-FILE-ID=SYNCHRONIZED>
 * @param <E> Type of component elements
 * @see ReadOnlyVector
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_BUILDER")
public final class ROVectorBuilder<E>
    extends Vector<E>
    implements RandomAccess, Cloneable, Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Fields & Builder
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    // Exception messages need this
    private static final String ROV = "Vector";

    private boolean built = false;

    // Mimics the C++ Concept of "Friend Class".  This badge is utilized by the "build()" method
    // directly below this inner-class declaration.  It is the only place where this declaration is
    // actually used anywhere.  This prohibits access to the constructor that is used to anybody
    // else

    static class AccessBadge { private AccessBadge() { } }
    private static final AccessBadge friendClassBadge = new AccessBadge();

    /**
     * Simply transfers {@code 'this'} instance' internal {@code Vector} to the 
     * {@code ReadOnlyVector} Wrapper-Class.
     * 
     * @return a newly constructed {@code ReadOnlyVector} "Wrapper-Class", shielding the
     * internal {@code 'vector'} private-field from any modification.
     */
    public synchronized ReadOnlyVector<E> build()
    {
        super.trimToSize();
        this.built = true;

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


    // ********************************************************************************************
    // ********************************************************************************************
    // Modified Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Constructs an empty vector with the specified initial capacity and capacity increment.
     * @param initialCapacity the initial capacity of the vector
     * 
     * @param capacityIncrement the amount by which the capacity is increased when the vector
     * overflows
     * 
     * @throws IllegalArgumentException if the specified initial capacity is negative
     */
    public ROVectorBuilder(int initialCapacity, int capacityIncrement)
    { super(initialCapacity, capacityIncrement); }

    /**
     * Constructs an empty vector with the specified initial capacity and with its capacity
     * increment equal to zero.
     *
     * @param initialCapacity the initial capacity of the vector
     * @throws IllegalArgumentException if the specified initial capacity is negative
     */
    public ROVectorBuilder(int initialCapacity)
    { super(initialCapacity); }

    /**
     * Constructs an empty vector so that its internal data array has size {@code 10} and its
     * standard capacity increment is zero.
     */
    public ROVectorBuilder()
    { super(); }

    /**
     * Constructs a vector containing the elements of the specified collection, in the order they
     * are returned by the collection's iterator.
     *
     * @param c the collection whose elements are to be placed into this vector
     * @throws NullPointerException if the specified collection is null
     */
    public ROVectorBuilder(Collection<? extends E> c)
    { super(c); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * 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 {@code elementData}, with a smaller
     * one. An application can use this operation to minimize the storage of a vector.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     */
    public synchronized void trimToSize()
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.trimToSize(); 
    }

    /**
     * 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.
     *
     * <BR /><BR />If the current capacity of this vector is less than {@code minCapacity}, then
     * its capacity is increased by replacing its internal data array, kept in the field
     * {@code elementData}, with a larger one.  The size of the new data array will be the old size
     * plus {@code capacityIncrement}, unless the value of {@code 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 {@code minCapacity}, then the new capacity will be
     * {@code minCapacity}.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param minCapacity the desired minimum capacity
     */
    public synchronized void ensureCapacity(int minCapacity)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.ensureCapacity(minCapacity); 
    }

    /**
     * Sets the size of this vector. If the new size is greater than the current size, new
     * {@code null} items are added to the end of the vector. If the new size is less than the
     * current size, all components at index {@code newSize} and greater are discarded.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param newSize the new size of this vector
     * @throws ArrayIndexOutOfBoundsException if the new size is negative
     */
    public synchronized void setSize(int newSize)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.setSize(newSize); 
    }

    /**
     * Sets the component at the specified {@code index} of this vector to be the specified object.
     * The previous component at that position is discarded.
     *
     * <BR /><BR />The index must be a value greater than or equal to {@code 0} and less than the
     * current size of the vector.
     *
     * <BR /><BR />This method is identical in functionality to the
     * {@link #set(int, Object) set(int, E)} method (which is part of the
     * {@link ReadOnlyList} interface). Note that the {@code set} method reverses the order of the
     * parameters, to more closely match array usage.  Note also that the {@code set} method
     * returns the old value that was stored at the specified position.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param obj what the component is to be set to
     * @param index the specified index
     * 
     * @throws ArrayIndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index >= size()})
     */
    public synchronized void setElementAt(E obj, int index)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.setElementAt(obj, index); 
    }

    /**
     * Deletes the component at the specified index. Each component in this vector with an index
     * greater or equal to the specified {@code index} is shifted downward to have an index one
     * smaller than the value it had previously. The size of this vector is decreased by {@code 1}.
     *
     * <BR /><BR />The index must be a value greater than or equal to {@code 0} and less than the
     * current size of the vector.
     *
     * <BR /><BR />This method is identical in functionality to the {@link #remove(int)} method
     * (which is part of the {@link ReadOnlyList} interface).  Note that the {@code remove} method
     * returns the old value that was stored at the specified position.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param index the index of the object to remove
     * 
     * @throws ArrayIndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index >= size()})
     */
    public synchronized void removeElementAt(int index)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.removeElementAt(index); 
    }

    /**
     * Inserts the specified object as a component in this vector at the specified {@code index}.
     * Each component in this vector with an index greater or equal to the specified {@code index}
     * is shifted upward to have an index one greater than the value it had previously.
     *
     * <BR /><BR />The index must be a value greater than or equal to {@code 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.)
     *
     * <BR /><BR />This method is identical in functionality to the
     * {@link #add(int, Object) add(int, E)} method (which is part of the {@link ReadOnlyList}
     * interface).  Note that the {@code add} method reverses the order of the parameters, to more
     * closely match array usage.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param obj the component to insert
     * @param index where to insert the new component
     * 
     * @throws ArrayIndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index > size()})
     */
    public synchronized void insertElementAt(E obj, int index)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.insertElementAt(obj, index); 
    }

    /**
     * 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.
     *
     * <BR /><BR />This method is identical in functionality to the {@link #add(Object) add(E)}
     * method (which is part of the {@link ReadOnlyList} interface).
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param obj the component to be added
     */
    public synchronized void addElement(E obj)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.addElement(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.
     *
     * <BR /><BR />This method is identical in functionality to the {@link #remove(Object)} method
     * (which is part of the {@link ReadOnlyList} interface).
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param obj the component to be removed
     * @return {@code TRUE} if the argument was a component of this vector; {@code FALSE} otherwise.
     */
    public synchronized boolean removeElement(Object obj)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        return super.removeElement(obj); 
    }

    /**
     * Removes all components from this vector and sets its size to zero.
     *
     * <BR /><BR />This method is identical in functionality to the {@link #clear} method (which is
     * part of the {@link ReadOnlyList} interface).
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     */
    public synchronized void removeAllElements()
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.removeAllElements(); 
    }

    /**
     * Replaces the element at the specified position in this Vector with the specified element.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param index index of the element to replace
     * @param element element to be stored at the specified position
     * @return the element previously at the specified position
     * 
     * @throws ArrayIndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index >= size()})
     */
    public synchronized E set(int index, E element)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        return super.set(index, element); 
    }

    /**
     * Appends the specified element to the end of this Vector.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param e element to be appended to this Vector
     * @return {@code TRUE} (as specified by {@code Collection.add})
     */
    public synchronized boolean add(E e)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        return super.add(e); 
    }

    /**
     * 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 {@code Objects.equals(o, get(i))} (if such an element exists).
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param o element to be removed from this Vector, if present
     * @return true if the Vector contained the specified element
     */
    public boolean remove(Object o)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        return super.remove(o); 
    }

    /**
     * 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).
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param index index at which the specified element is to be inserted
     * @param element element to be inserted
     * 
     * @throws ArrayIndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index > size()})
     */
    public void add(int index, E element)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.add(index, element); 
    }

    /**
     * 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.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param index the index of the element to be removed
     * @return element that was removed
     * 
     * @throws ArrayIndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index >= size()})
     */
    public synchronized E remove(int index)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        return super.remove(index); 
    }

    /**
     * Removes all of the elements from this Vector.  The Vector will be empty after this call
     * returns (unless it throws an exception).
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     */
    public void clear()
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.clear(); 
    }

    /**
     * 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.)
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param c elements to be inserted into this Vector
     * @return {@code TRUE} if this Vector changed as a result of the call
     * @throws NullPointerException if the specified collection is null
     */
    public boolean addAll(Collection<? extends E> c)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        return super.addAll(c); 
    }

    /**
     * Removes from this Vector all of its elements that are contained in the specified Collection.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param c a collection of elements to be removed from the Vector
     * @return true if this Vector changed as a result of the call
     * 
     * @throws ClassCastException if the types of one or more elements in this vector are
     * incompatible with the specified collection
     * (<a href="Collection.html#optional-restrictions">optional</a>)
     * 
     * @throws NullPointerException if this vector contains one or more null elements and the
     * specified collection does not support null elements
     * (<a href="Collection.html#optional-restrictions">optional</a>),
     * or if the specified collection is null
     */
    public boolean removeAll(Collection<?> c)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        return super.removeAll(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.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param c a collection of elements to be retained in this Vector (all other elements are
     * removed)
     * 
     * @return true if this Vector changed as a result of the call
     * 
     * @throws ClassCastException if the types of one or more elements in this vector are
     * incompatible with the specified collection
     * (<a href="Collection.html#optional-restrictions">optional</a>)
     * 
     * @throws NullPointerException if this vector contains one or more null elements and the
     * specified collection does not support null elements
     * (<a href="Collection.html#optional-restrictions">optional</a>),
     * or if the specified collection is null
     */
    public boolean retainAll(Collection<?> c)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        return super.retainAll(c); 
    }

    /**
     * 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.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param filter a {@code Predicate} which returns {@code TRUE} for elements to be removed
     * @return {@code TRUE} if any elements were removed
     * @throws NullPointerException  if the specified filter is null
     */
    public boolean removeIf(Predicate<? super E> filter)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        return super.removeIf(filter); 
    }

    /**
     * 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.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param index index at which to insert the first element from the specified collection
     * @param c elements to be inserted into this Vector
     * @return {@code TRUE} if this Vector changed as a result of the call
     * 
     * @throws ArrayIndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index > size()})
     * 
     * @throws NullPointerException if the specified collection is null
     */
    public synchronized boolean addAll(int index, Collection<? extends E> c)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        return super.addAll(index, c); 
    }

    /**
     * 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.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param operator the operator to apply to each element
     * 
     * @throws 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)
     */
    public synchronized void replaceAll(UnaryOperator<E> operator)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.replaceAll(operator); 
    }

    /**
     * Sorts this list according to the order induced by the specified {@code Comparator}. The sort
     * is stable: this method must not reorder equal elements.
     * 
     * <BR /><BR />All elements in this list must be mutually comparable using the specified
     * comparator (that is, {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
     * for any elements {@code e1} and {@code e2} in the list).
     * 
     * <BR /><BR />If the specified comparator is null then all elements in this list must
     * implement the {@code Comparable} interface and the elements' natural ordering should be
     * used.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param c the Comparator used to compare list elements. A null value indicates that the
     * elements' natural ordering should be used
     * 
     * @throws ClassCastException if the list contains elements that are not mutually comparable
     * using the specified comparator
     * 
     * @throws IllegalArgumentException if the comparator is found to violate the
     * {@code Comparator} contract
     */
    public synchronized void sort(Comparator<? super E> c)
    {
        if (this.built) throw new AttemptedModificationException(ROV);
        super.sort(c); 
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Methods inherited from class java.util.Vector
    // ********************************************************************************************
    // ********************************************************************************************


    // capacity, contains, containsAll, copyInto, elementAt, elements, firstElement, forEach, get,
    // hashCode, indexOf, indexOf, isEmpty, iterator, lastElement, lastIndexOf, lastIndexOf,
    // listIterator, listIterator, removeRange, size, spliterator, subList, toArray, toArray,
    // toString
    //
    // Introspection-Only: 
    // capacity, contains, containsAll, copyInto, elementAt, elements, firstElement, forEach, get,
    // hashCode, indexOf, indexOf, isEmpty, lastElement, lastIndexOf, lastIndexOf, size,
    // spliterator, toArray, toArray, toString
    //
    // Potential Mutator Methods: iterator, listIterator, listIterator, subList
    //
    // Protected Method (Don't worry about it): removeRange
    // 
    // Methods inherited from interface java.util.Collection: parallelStream, stream, toArray

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=Iterator DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.Iterator} that cannot modify this {@code Vector-Builder}
     */
    public RemoveUnsupportedIterator<E> iterator()
    { return new RemoveUnsupportedIterator<>(super.iterator()); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=ListIterator DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.ListIterator} that cannot modify this {@code Vector-Builder}
     */
    public ListIterator<E> listIterator()
    { return ROHelpers.removeUnsupportedListIterator(super.listIterator()); }

    ListIterator<E> _listIterator(ReadOnlyVector.AccessBadge friendClassBadge)
    { return super.listIterator(); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=ListIterator DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.ListIterator} that cannot modify this {@code Vector-Builder}
     */
    public ListIterator<E> listIterator(int index)
    { return ROHelpers.removeUnsupportedListIterator(super.listIterator(index)); }

    ListIterator<E> _listIterator(int index, ReadOnlyVector.AccessBadge friendClassBadge)
    { return super.listIterator(index); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=List DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.List} that cannot modify this {@code Vector-Builder}
     */
    public List<E> subList(int fromIndex, int toIndex)
    { return Collections.unmodifiableList(super.subList(fromIndex, toIndex)); }

    List<E> _subList(int fromIndex, int toIndex, ReadOnlyVector.AccessBadge friendClassBadge)
    { return super.subList(fromIndex, toIndex); }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object & Cloneable
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Compares the specified Object with this Builder for equality, as per the definition in the
     * private and internal field {@code 'vector'}.
     *
     * @param  o object to be compared for equality with this {@code ROVectorBuilder} instance
     * @return true if the specified Object is equal to this Builder
     */
    public synchronized boolean equals(Object o)
    {
        if (this == o) return true;
        if (! (o instanceof ROVectorBuilder)) return false;
        return super.equals((ROVectorBuilder) o);
    }

    /**
     * Clones this instance' of {@code ROVectorBuilder}.
     * 
     * <BR /><BR />The clone that's returned has had it's internal {@code 'built'} boolean-flag set
     * {@code FALSE}
     * 
     * @return a clone of this builder
     */
    public synchronized ROVectorBuilder<E> clone()
    { return new ROVectorBuilder<>(this); }

    private ROVectorBuilder(ROVectorBuilder<E> rovb)
    { super(rovb); this.built=false; }
}