001/*
002 * Copyright (c) 1994, 2018, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025package Torello.Java.ReadOnly;
026
027import java.io.Serializable;
028
029import java.util.function.Predicate;
030import java.util.function.UnaryOperator;
031
032import Torello.Java.Additional.RemoveUnsupportedIterator;
033
034import java.util.*;
035
036/**
037 * A Copy of Java's {@code Vector} class; used for building a {@link ReadOnlyVector}.
038 * Maintains <I>an internal and inaccessible {@code Vector<E>} instance</I>. 
039 * 
040 * <EMBED CLASS=globalDefs DATA-JDK=Vector>
041 * <EMBED CLASS='external-html' DATA-A_AN=a DATA-FILE-ID=BUILDERS>
042 * <EMBED CLASS='external-html' DATA-FILE-ID=SYNCHRONIZED>
043 * @param <E> Type of component elements
044 * @see ReadOnlyVector
045 */
046@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_BUILDER")
047public final class ROVectorBuilder<E>
048    extends Vector<E>
049    implements RandomAccess, Cloneable, Serializable
050{
051    // ********************************************************************************************
052    // ********************************************************************************************
053    // Fields & Builder
054    // ********************************************************************************************
055    // ********************************************************************************************
056
057
058    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
059    protected static final long serialVersionUID = 1;
060
061    // Exception messages need this
062    private static final String ROV = "Vector";
063
064    private boolean built = false;
065
066    // Mimics the C++ Concept of "Friend Class".  This badge is utilized by the "build()" method
067    // directly below this inner-class declaration.  It is the only place where this declaration is
068    // actually used anywhere.  This prohibits access to the constructor that is used to anybody
069    // else
070
071    static class AccessBadge { private AccessBadge() { } }
072    private static final AccessBadge friendClassBadge = new AccessBadge();
073
074    /**
075     * Simply transfers {@code 'this'} instance' internal {@code Vector} to the 
076     * {@code ReadOnlyVector} Wrapper-Class.
077     * 
078     * @return a newly constructed {@code ReadOnlyVector} "Wrapper-Class", shielding the
079     * internal {@code 'vector'} private-field from any modification.
080     */
081    public synchronized ReadOnlyVector<E> build()
082    {
083        super.trimToSize();
084        this.built = true;
085
086        return (size() == 0)
087            ? ReadOnlyVector.emptyROV()
088            : new ReadOnlyVector<>(this, friendClassBadge);
089    }
090
091
092    // ********************************************************************************************
093    // ********************************************************************************************
094    // Modified Constructors
095    // ********************************************************************************************
096    // ********************************************************************************************
097
098
099    /**
100     * Constructs an empty vector with the specified initial capacity and capacity increment.
101     * @param initialCapacity the initial capacity of the vector
102     * 
103     * @param capacityIncrement the amount by which the capacity is increased when the vector
104     * overflows
105     * 
106     * @throws IllegalArgumentException if the specified initial capacity is negative
107     */
108    public ROVectorBuilder(int initialCapacity, int capacityIncrement)
109    { super(initialCapacity, capacityIncrement); }
110
111    /**
112     * Constructs an empty vector with the specified initial capacity and with its capacity
113     * increment equal to zero.
114     *
115     * @param initialCapacity the initial capacity of the vector
116     * @throws IllegalArgumentException if the specified initial capacity is negative
117     */
118    public ROVectorBuilder(int initialCapacity)
119    { super(initialCapacity); }
120
121    /**
122     * Constructs an empty vector so that its internal data array has size {@code 10} and its
123     * standard capacity increment is zero.
124     */
125    public ROVectorBuilder()
126    { super(); }
127
128    /**
129     * Constructs a vector containing the elements of the specified collection, in the order they
130     * are returned by the collection's iterator.
131     *
132     * @param c the collection whose elements are to be placed into this vector
133     * @throws NullPointerException if the specified collection is null
134     */
135    public ROVectorBuilder(Collection<? extends E> c)
136    { super(c); }
137
138
139    // ********************************************************************************************
140    // ********************************************************************************************
141    // Original JDK Methods
142    // ********************************************************************************************
143    // ********************************************************************************************
144
145
146    /**
147     * Trims the capacity of this vector to be the vector's current size. If the capacity of this
148     * vector is larger than its current size, then the capacity is changed to equal the size by
149     * replacing its internal data array, kept in the field {@code elementData}, with a smaller
150     * one. An application can use this operation to minimize the storage of a vector.
151     * 
152     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
153     */
154    public synchronized void trimToSize()
155    {
156        if (this.built) throw new AttemptedModificationException(ROV);
157        super.trimToSize(); 
158    }
159
160    /**
161     * Increases the capacity of this vector, if necessary, to ensure that it can hold at least the
162     * number of components specified by the minimum capacity argument.
163     *
164     * <BR /><BR />If the current capacity of this vector is less than {@code minCapacity}, then
165     * its capacity is increased by replacing its internal data array, kept in the field
166     * {@code elementData}, with a larger one.  The size of the new data array will be the old size
167     * plus {@code capacityIncrement}, unless the value of {@code capacityIncrement} is less than
168     * or equal to zero, in which case the new capacity will be twice the old capacity; but if this
169     * new size is still smaller than {@code minCapacity}, then the new capacity will be
170     * {@code minCapacity}.
171     * 
172     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
173     *
174     * @param minCapacity the desired minimum capacity
175     */
176    public synchronized void ensureCapacity(int minCapacity)
177    {
178        if (this.built) throw new AttemptedModificationException(ROV);
179        super.ensureCapacity(minCapacity); 
180    }
181
182    /**
183     * Sets the size of this vector. If the new size is greater than the current size, new
184     * {@code null} items are added to the end of the vector. If the new size is less than the
185     * current size, all components at index {@code newSize} and greater are discarded.
186     * 
187     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
188     *
189     * @param newSize the new size of this vector
190     * @throws ArrayIndexOutOfBoundsException if the new size is negative
191     */
192    public synchronized void setSize(int newSize)
193    {
194        if (this.built) throw new AttemptedModificationException(ROV);
195        super.setSize(newSize); 
196    }
197
198    /**
199     * Sets the component at the specified {@code index} of this vector to be the specified object.
200     * The previous component at that position is discarded.
201     *
202     * <BR /><BR />The index must be a value greater than or equal to {@code 0} and less than the
203     * current size of the vector.
204     *
205     * <BR /><BR />This method is identical in functionality to the
206     * {@link #set(int, Object) set(int, E)} method (which is part of the
207     * {@link ReadOnlyList} interface). Note that the {@code set} method reverses the order of the
208     * parameters, to more closely match array usage.  Note also that the {@code set} method
209     * returns the old value that was stored at the specified position.
210     * 
211     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
212     *
213     * @param obj what the component is to be set to
214     * @param index the specified index
215     * 
216     * @throws ArrayIndexOutOfBoundsException if the index is out of range
217     * ({@code index < 0 || index >= size()})
218     */
219    public synchronized void setElementAt(E obj, int index)
220    {
221        if (this.built) throw new AttemptedModificationException(ROV);
222        super.setElementAt(obj, index); 
223    }
224
225    /**
226     * Deletes the component at the specified index. Each component in this vector with an index
227     * greater or equal to the specified {@code index} is shifted downward to have an index one
228     * smaller than the value it had previously. The size of this vector is decreased by {@code 1}.
229     *
230     * <BR /><BR />The index must be a value greater than or equal to {@code 0} and less than the
231     * current size of the vector.
232     *
233     * <BR /><BR />This method is identical in functionality to the {@link #remove(int)} method
234     * (which is part of the {@link ReadOnlyList} interface).  Note that the {@code remove} method
235     * returns the old value that was stored at the specified position.
236     * 
237     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
238     *
239     * @param index the index of the object to remove
240     * 
241     * @throws ArrayIndexOutOfBoundsException if the index is out of range
242     * ({@code index < 0 || index >= size()})
243     */
244    public synchronized void removeElementAt(int index)
245    {
246        if (this.built) throw new AttemptedModificationException(ROV);
247        super.removeElementAt(index); 
248    }
249
250    /**
251     * Inserts the specified object as a component in this vector at the specified {@code index}.
252     * Each component in this vector with an index greater or equal to the specified {@code index}
253     * is shifted upward to have an index one greater than the value it had previously.
254     *
255     * <BR /><BR />The index must be a value greater than or equal to {@code 0} and less than or
256     * equal to the current size of the vector. (If the index is equal to the current size of the
257     * vector, the new element is appended to the Vector.)
258     *
259     * <BR /><BR />This method is identical in functionality to the
260     * {@link #add(int, Object) add(int, E)} method (which is part of the {@link ReadOnlyList}
261     * interface).  Note that the {@code add} method reverses the order of the parameters, to more
262     * closely match array usage.
263     * 
264     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
265     *
266     * @param obj the component to insert
267     * @param index where to insert the new component
268     * 
269     * @throws ArrayIndexOutOfBoundsException if the index is out of range
270     * ({@code index < 0 || index > size()})
271     */
272    public synchronized void insertElementAt(E obj, int index)
273    {
274        if (this.built) throw new AttemptedModificationException(ROV);
275        super.insertElementAt(obj, index); 
276    }
277
278    /**
279     * Adds the specified component to the end of this vector, increasing its size by one.  The 
280     * capacity of this vector is increased if its size becomes greater than its capacity.
281     *
282     * <BR /><BR />This method is identical in functionality to the {@link #add(Object) add(E)}
283     * method (which is part of the {@link ReadOnlyList} interface).
284     * 
285     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
286     *
287     * @param obj the component to be added
288     */
289    public synchronized void addElement(E obj)
290    {
291        if (this.built) throw new AttemptedModificationException(ROV);
292        super.addElement(obj); 
293    }
294
295    /**
296     * Removes the first (lowest-indexed) occurrence of the argument from this vector. If the
297     * object is found in this vector, each component in the vector with an index greater or equal
298     * to the object's index is shifted downward to have an index one smaller than the value it had
299     * previously.
300     *
301     * <BR /><BR />This method is identical in functionality to the {@link #remove(Object)} method
302     * (which is part of the {@link ReadOnlyList} interface).
303     * 
304     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
305     *
306     * @param obj the component to be removed
307     * @return {@code TRUE} if the argument was a component of this vector; {@code FALSE} otherwise.
308     */
309    public synchronized boolean removeElement(Object obj)
310    {
311        if (this.built) throw new AttemptedModificationException(ROV);
312        return super.removeElement(obj); 
313    }
314
315    /**
316     * Removes all components from this vector and sets its size to zero.
317     *
318     * <BR /><BR />This method is identical in functionality to the {@link #clear} method (which is
319     * part of the {@link ReadOnlyList} interface).
320     * 
321     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
322     */
323    public synchronized void removeAllElements()
324    {
325        if (this.built) throw new AttemptedModificationException(ROV);
326        super.removeAllElements(); 
327    }
328
329    /**
330     * Replaces the element at the specified position in this Vector with the specified element.
331     * 
332     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
333     * 
334     * @param index index of the element to replace
335     * @param element element to be stored at the specified position
336     * @return the element previously at the specified position
337     * 
338     * @throws ArrayIndexOutOfBoundsException if the index is out of range
339     * ({@code index < 0 || index >= size()})
340     */
341    public synchronized E set(int index, E element)
342    {
343        if (this.built) throw new AttemptedModificationException(ROV);
344        return super.set(index, element); 
345    }
346
347    /**
348     * Appends the specified element to the end of this Vector.
349     * 
350     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
351     * 
352     * @param e element to be appended to this Vector
353     * @return {@code TRUE} (as specified by {@code Collection.add})
354     */
355    public synchronized boolean add(E e)
356    {
357        if (this.built) throw new AttemptedModificationException(ROV);
358        return super.add(e); 
359    }
360
361    /**
362     * Removes the first occurrence of the specified element in this Vector If the Vector does not
363     * contain the element, it is unchanged.  More formally, removes the element with the lowest
364     * index i such that {@code Objects.equals(o, get(i))} (if such an element exists).
365     * 
366     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
367     *
368     * @param o element to be removed from this Vector, if present
369     * @return true if the Vector contained the specified element
370     */
371    public boolean remove(Object o)
372    {
373        if (this.built) throw new AttemptedModificationException(ROV);
374        return super.remove(o); 
375    }
376
377    /**
378     * Inserts the specified element at the specified position in this Vector.  Shifts the element
379     * currently at that position (if any) and any subsequent elements to the right (adds one to
380     * their indices).
381     * 
382     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
383     *
384     * @param index index at which the specified element is to be inserted
385     * @param element element to be inserted
386     * 
387     * @throws ArrayIndexOutOfBoundsException if the index is out of range
388     * ({@code index < 0 || index > size()})
389     */
390    public void add(int index, E element)
391    {
392        if (this.built) throw new AttemptedModificationException(ROV);
393        super.add(index, element); 
394    }
395
396    /**
397     * Removes the element at the specified position in this Vector.  Shifts any subsequent
398     * elements to the left (subtracts one from their indices).  Returns the element that was
399     * removed from the Vector.
400     * 
401     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
402     *
403     * @param index the index of the element to be removed
404     * @return element that was removed
405     * 
406     * @throws ArrayIndexOutOfBoundsException if the index is out of range
407     * ({@code index < 0 || index >= size()})
408     */
409    public synchronized E remove(int index)
410    {
411        if (this.built) throw new AttemptedModificationException(ROV);
412        return super.remove(index); 
413    }
414
415    /**
416     * Removes all of the elements from this Vector.  The Vector will be empty after this call
417     * returns (unless it throws an exception).
418     * 
419     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
420     */
421    public void clear()
422    {
423        if (this.built) throw new AttemptedModificationException(ROV);
424        super.clear(); 
425    }
426
427    /**
428     * Appends all of the elements in the specified Collection to the end of this Vector, in the
429     * order that they are returned by the specified Collection's Iterator.  The behavior of this
430     * operation is undefined if the specified Collection is modified while the operation is in
431     * progress.  (This implies that the behavior of this call is undefined if the specified
432     * Collection is this Vector, and this Vector is nonempty.)
433     * 
434     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
435     *
436     * @param c elements to be inserted into this Vector
437     * @return {@code TRUE} if this Vector changed as a result of the call
438     * @throws NullPointerException if the specified collection is null
439     */
440    public boolean addAll(Collection<? extends E> c)
441    {
442        if (this.built) throw new AttemptedModificationException(ROV);
443        return super.addAll(c); 
444    }
445
446    /**
447     * Removes from this Vector all of its elements that are contained in the specified Collection.
448     * 
449     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
450     *
451     * @param c a collection of elements to be removed from the Vector
452     * @return true if this Vector changed as a result of the call
453     * 
454     * @throws ClassCastException if the types of one or more elements in this vector are
455     * incompatible with the specified collection
456     * (<a href="Collection.html#optional-restrictions">optional</a>)
457     * 
458     * @throws NullPointerException if this vector contains one or more null elements and the
459     * specified collection does not support null elements
460     * (<a href="Collection.html#optional-restrictions">optional</a>),
461     * or if the specified collection is null
462     */
463    public boolean removeAll(Collection<?> c)
464    {
465        if (this.built) throw new AttemptedModificationException(ROV);
466        return super.removeAll(c); 
467    }
468
469    /**
470     * Retains only the elements in this Vector that are contained in the specified Collection.  In
471     * other words, removes from this Vector all of its elements that are not contained in the
472     * specified Collection.
473     * 
474     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
475     *
476     * @param c a collection of elements to be retained in this Vector (all other elements are
477     * removed)
478     * 
479     * @return true if this Vector changed as a result of the call
480     * 
481     * @throws ClassCastException if the types of one or more elements in this vector are
482     * incompatible with the specified collection
483     * (<a href="Collection.html#optional-restrictions">optional</a>)
484     * 
485     * @throws NullPointerException if this vector contains one or more null elements and the
486     * specified collection does not support null elements
487     * (<a href="Collection.html#optional-restrictions">optional</a>),
488     * or if the specified collection is null
489     */
490    public boolean retainAll(Collection<?> c)
491    {
492        if (this.built) throw new AttemptedModificationException(ROV);
493        return super.retainAll(c); 
494    }
495
496    /**
497     * Removes all of the elements of this collection that satisfy the given predicate. Errors or
498     * runtime exceptions thrown during iteration or by the predicate are relayed to the caller.
499     * 
500     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
501     * 
502     * @param filter a {@code Predicate} which returns {@code TRUE} for elements to be removed
503     * @return {@code TRUE} if any elements were removed
504     * @throws NullPointerException  if the specified filter is null
505     */
506    public boolean removeIf(Predicate<? super E> filter)
507    {
508        if (this.built) throw new AttemptedModificationException(ROV);
509        return super.removeIf(filter); 
510    }
511
512    /**
513     * Inserts all of the elements in the specified Collection into this Vector at the specified
514     * position.  Shifts the element currently at that position (if any) and any subsequent
515     * elements to the right (increases their indices).  The new elements will appear in the Vector
516     * in the order that they are returned by the specified Collection's iterator.
517     * 
518     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
519     * 
520     * @param index index at which to insert the first element from the specified collection
521     * @param c elements to be inserted into this Vector
522     * @return {@code TRUE} if this Vector changed as a result of the call
523     * 
524     * @throws ArrayIndexOutOfBoundsException if the index is out of range
525     * ({@code index < 0 || index > size()})
526     * 
527     * @throws NullPointerException if the specified collection is null
528     */
529    public synchronized boolean addAll(int index, Collection<? extends E> c)
530    {
531        if (this.built) throw new AttemptedModificationException(ROV);
532        return super.addAll(index, c); 
533    }
534
535    /**
536     * Replaces each element of this list with the result of applying the operator to that element.
537     * Errors or runtime exceptions thrown by the operator are relayed to the caller.
538     * 
539     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
540     * 
541     * @param operator the operator to apply to each element
542     * 
543     * @throws NullPointerException if the specified operator is null or if the operator result is
544     * a null value and this list does not permit null elements (optional)
545     */
546    public synchronized void replaceAll(UnaryOperator<E> operator)
547    {
548        if (this.built) throw new AttemptedModificationException(ROV);
549        super.replaceAll(operator); 
550    }
551
552    /**
553     * Sorts this list according to the order induced by the specified {@code Comparator}. The sort
554     * is stable: this method must not reorder equal elements.
555     * 
556     * <BR /><BR />All elements in this list must be mutually comparable using the specified
557     * comparator (that is, {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
558     * for any elements {@code e1} and {@code e2} in the list).
559     * 
560     * <BR /><BR />If the specified comparator is null then all elements in this list must
561     * implement the {@code Comparable} interface and the elements' natural ordering should be
562     * used.
563     * 
564     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
565     * 
566     * @param c the Comparator used to compare list elements. A null value indicates that the
567     * elements' natural ordering should be used
568     * 
569     * @throws ClassCastException if the list contains elements that are not mutually comparable
570     * using the specified comparator
571     * 
572     * @throws IllegalArgumentException if the comparator is found to violate the
573     * {@code Comparator} contract
574     */
575    public synchronized void sort(Comparator<? super E> c)
576    {
577        if (this.built) throw new AttemptedModificationException(ROV);
578        super.sort(c); 
579    }
580
581
582    // ********************************************************************************************
583    // ********************************************************************************************
584    // Methods inherited from class java.util.Vector
585    // ********************************************************************************************
586    // ********************************************************************************************
587
588
589    // capacity, contains, containsAll, copyInto, elementAt, elements, firstElement, forEach, get,
590    // hashCode, indexOf, indexOf, isEmpty, iterator, lastElement, lastIndexOf, lastIndexOf,
591    // listIterator, listIterator, removeRange, size, spliterator, subList, toArray, toArray,
592    // toString
593    //
594    // Introspection-Only: 
595    // capacity, contains, containsAll, copyInto, elementAt, elements, firstElement, forEach, get,
596    // hashCode, indexOf, indexOf, isEmpty, lastElement, lastIndexOf, lastIndexOf, size,
597    // spliterator, toArray, toArray, toString
598    //
599    // Potential Mutator Methods: iterator, listIterator, listIterator, subList
600    //
601    // Protected Method (Don't worry about it): removeRange
602    // 
603    // Methods inherited from interface java.util.Collection: parallelStream, stream, toArray
604
605    /**
606     * Restricts a back-door into the underlying data-structure.
607     * <EMBED CLASS='external-html'DATA-RET_TYPE=Iterator DATA-FILE-ID=UNMODIFIABLE>
608     * @return a {@code java.util.Iterator} that cannot modify this {@code Vector-Builder}
609     */
610    public RemoveUnsupportedIterator<E> iterator()
611    { return new RemoveUnsupportedIterator<>(super.iterator()); }
612
613    /**
614     * Restricts a back-door into the underlying data-structure.
615     * <EMBED CLASS='external-html'DATA-RET_TYPE=ListIterator DATA-FILE-ID=UNMODIFIABLE>
616     * @return a {@code java.util.ListIterator} that cannot modify this {@code Vector-Builder}
617     */
618    public ListIterator<E> listIterator()
619    { return ROHelpers.removeUnsupportedListIterator(super.listIterator()); }
620
621    ListIterator<E> _listIterator(ReadOnlyVector.AccessBadge friendClassBadge)
622    { return super.listIterator(); }
623
624    /**
625     * Restricts a back-door into the underlying data-structure.
626     * <EMBED CLASS='external-html'DATA-RET_TYPE=ListIterator DATA-FILE-ID=UNMODIFIABLE>
627     * @return a {@code java.util.ListIterator} that cannot modify this {@code Vector-Builder}
628     */
629    public ListIterator<E> listIterator(int index)
630    { return ROHelpers.removeUnsupportedListIterator(super.listIterator(index)); }
631
632    ListIterator<E> _listIterator(int index, ReadOnlyVector.AccessBadge friendClassBadge)
633    { return super.listIterator(index); }
634
635    /**
636     * Restricts a back-door into the underlying data-structure.
637     * <EMBED CLASS='external-html'DATA-RET_TYPE=List DATA-FILE-ID=UNMODIFIABLE>
638     * @return a {@code java.util.List} that cannot modify this {@code Vector-Builder}
639     */
640    public List<E> subList(int fromIndex, int toIndex)
641    { return Collections.unmodifiableList(super.subList(fromIndex, toIndex)); }
642
643    List<E> _subList(int fromIndex, int toIndex, ReadOnlyVector.AccessBadge friendClassBadge)
644    { return super.subList(fromIndex, toIndex); }
645
646
647    // ********************************************************************************************
648    // ********************************************************************************************
649    // java.lang.Object & Cloneable
650    // ********************************************************************************************
651    // ********************************************************************************************
652
653
654    /**
655     * Compares the specified Object with this Builder for equality, as per the definition in the
656     * private and internal field {@code 'vector'}.
657     *
658     * @param  o object to be compared for equality with this {@code ROVectorBuilder} instance
659     * @return true if the specified Object is equal to this Builder
660     */
661    public synchronized boolean equals(Object o)
662    {
663        if (this == o) return true;
664        if (! (o instanceof ROVectorBuilder)) return false;
665        return super.equals((ROVectorBuilder) o);
666    }
667
668    /**
669     * Clones this instance' of {@code ROVectorBuilder}.
670     * 
671     * <BR /><BR />The clone that's returned has had it's internal {@code 'built'} boolean-flag set
672     * {@code FALSE}
673     * 
674     * @return a clone of this builder
675     */
676    public synchronized ROVectorBuilder<E> clone()
677    { return new ROVectorBuilder<>(this); }
678
679    private ROVectorBuilder(ROVectorBuilder<E> rovb)
680    { super(rovb); this.built=false; }
681}
682