Class ROArrayListBuilder<E>

  • Type Parameters:
    E - the type of elements in this list
    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 ROArrayListBuilder<E>
extends java.util.ArrayList<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 ArrayList class; used for building a ReadOnlyArrayList. Maintains an internal and inaccessible ArrayList<E> instance. Upon build completion, this instance is passed to the ReadOnlyArrayList 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 ReadOnlyArrayList 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 an ArrayList 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 ReadOnlyArrayList 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.ArrayList (explained further, below), making it extremely easy to use.

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

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


    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static long serialVersionUID

      • Fields inherited from class java.util.AbstractList

        modCount

    • Constructor Summary

      Constructors 
      Constructor Description
      ROArrayListBuilder()
      Constructs an empty list with an initial capacity of ten.
      ROArrayListBuilder​(int initialCapacity)
      Constructs an empty ROArrayListBuilder with the specified initial capacity.
      ROArrayListBuilder​(Collection<? extends E> c)
      Constructs a ROArrayListBuilder 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 ReadOnlyArrayList instance
      Modifier and Type Method
      ReadOnlyArrayList<E> build()
      Simply transfers 'this' instance' internal ArrayList to the ReadOnlyArrayList 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 list.
      boolean add​(E e)
      Appends the specified element to the end of this list.
      boolean addAll​(int index, Collection<? extends E> c)
      Inserts all of the elements in the specified collection into this list, starting at the specified position.
      boolean addAll​(Collection<? extends E> c)
      Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator.
       
      Remove Items from this Read-Only-List Builder
      Modifier and Type Method
      void clear()
      Removes all of the elements from this list.
      E remove​(int index)
      Removes the element at the specified position in this list.
      boolean remove​(Object o)
      Removes the first occurrence of the specified element from this list, if it is present.
      boolean removeAll​(Collection<?> c)
      Removes from this list all of its elements that are contained in the specified collection.
      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 list 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 list with the specified element.
       
      JDK Standard ArrayList Methods
      Modifier and Type Method
      void ensureCapacity​(int minCapacity)
      Increases the capacity of this ArrayList instance, if necessary, to ensure that it can hold at least the number of elements specified by the minimum capacity argument.
      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 ArrayList instance to be the list'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 original class ArrayList.
       
      Methods: interface java.lang.Iterable
      Modifier and Type Method
      RemoveUnsupportedIterator<E> iterator()
      Restricted-Access Instance
       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method
      ROArrayListBuilder<E> clone()
      Clones this instance' of ROArrayListBuilder.

      • Methods inherited from class java.util.ArrayList

        contains, forEach, get, hashCode, indexOf, isEmpty, lastIndexOf, removeRange, size, spliterator, toArray, toArray

      • Methods inherited from class java.util.AbstractCollection

        containsAll, toString

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.util.Collection

        parallelStream, stream, toArray

      • Methods inherited from interface java.util.List

        containsAll

    • 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

      • ROArrayListBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROArrayListBuilder​(int initialCapacity)
        Constructs an empty ROArrayListBuilder with the specified initial capacity.
        Parameters:
        initialCapacity - the initial capacity of the list
        Throws:
        java.lang.IllegalArgumentException - if the specified initial capacity is negative
        Code:
        Exact Constructor Body:
         super(initialCapacity);

      • ROArrayListBuilder

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ROArrayListBuilder​(java.util.Collection<? extends E> c)
        Constructs a ROArrayListBuilder 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 list
        Throws:
        java.lang.NullPointerException - if the specified collection is null
        Code:
        Exact Constructor Body:
         super(c);

    • Method Detail

      • build

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

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

      • trimToSize

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void trimToSize()
        Trims the capacity of this ArrayList instance to be the list's current size. An application can use this operation to minimize the storage of an ArrayList instance.

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

      • ensureCapacity

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

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList field will throw an exception if invoked after a call to build().
        Overrides:
        ensureCapacity in class java.util.ArrayList<E>
        Parameters:
        minCapacity - the desired minimum capacity
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 super.ensureCapacity(minCapacity);

      • set

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

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<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.IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size())
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 return super.set(index, element);

      • add

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

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<E>
        Parameters:
        e - element to be appended to this list
        Returns:
        TRUE (as specified by Collection.add)
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 return super.add(e);

      • add

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void add​(int index,
                E element)
        Inserts the specified element at the specified position in this list. 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 ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<E>
        Parameters:
        index - index at which the specified element is to be inserted
        element - element to be inserted
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 super.add(index, element);

      • remove

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

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<E>
        Parameters:
        index - the index of the element to be removed
        Returns:
        the element that was removed from the list
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 return super.remove(index);

      • remove

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean remove​(java.lang.Object o)
        Removes the first occurrence of the specified element from this list, if it is present. If the list 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). Returns TRUE if this list contained the specified element (or equivalently, if this list changed as a result of the call).

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<E>
        Parameters:
        o - element to be removed from this list, if present
        Returns:
        TRUE if this list contained the specified element
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 return super.remove(o);

      • clear

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

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<E>
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 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 list, 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 list, and this list is nonempty.)

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<E>
        Parameters:
        c - collection containing elements to be added to this list
        Returns:
        TRUE if this list 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(ROAL);
 return super.addAll(c);

      • addAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean addAll​(int index,
                      java.util.Collection<? extends E> c)
        Inserts all of the elements in the specified collection into this list, starting 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 list in the order that they are returned by the specified collection's iterator.

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<E>
        Parameters:
        index - index at which to insert the first element from the specified collection
        c - collection containing elements to be added to this list
        Returns:
        TRUE if this list changed as a result of the call
        Throws:
        java.lang.NullPointerException - if the specified collection is null
        java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size())
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 return super.addAll(index, c);

      • removeAll

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

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<E>
        Parameters:
        c - collection containing elements to be removed from this list
        Returns:
        TRUE if this list changed as a result of the call
        Throws:
        java.lang.ClassCastException - if the class of an element of this list is incompatible with the specified collection (optional)
        java.lang.NullPointerException - if this list contains a null element and the specified collection does not permit null elements (optional), or if the specified collection is null
        See Also:
        ReadOnlyCollection.contains(Object)
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 return super.removeAll(c);

      • retainAll

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

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<E>
        Parameters:
        c - collection containing elements to be retained in this list
        Returns:
        TRUE if this list changed as a result of the call
        Throws:
        java.lang.ClassCastException - if the class of an element of this list is incompatible with the specified collection (optional)
        java.lang.NullPointerException - if this list contains a null element and the specified collection does not permit null elements (optional), or if the specified collection is null
        See Also:
        ReadOnlyCollection.contains(Object)
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 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 ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<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 parameter 'filter' has been passed null.
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 return super.removeIf(filter);

      • 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 ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<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(ROAL);
 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.

        This list must be modifiable, but need not be resizable.

        Mutator Method:
        This method modifies the contents of this class' internal ArrayList. Note that any method which modifies this internal ArrayList 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.ArrayList<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 - (optional) if the comparator is found to violate the Comparator contract
        Code:
        Exact Method Body:
         if (this.built) throw new AttemptedModificationException(ROAL);
 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 ArrayList 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 ArrayList) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyArrayList 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 ArrayList-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.ArrayList<E>
        Returns:
        a java.util.Iterator that cannot modify this ArrayList-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 ArrayList 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 ArrayList) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyArrayList 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 ArrayList-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        listIterator in interface java.util.List<E>
        Overrides:
        listIterator in class java.util.ArrayList<E>
        Returns:
        a java.util.ListIterator that cannot modify this ArrayList-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 ArrayList 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 ArrayList) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyArrayList 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 ArrayList-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        listIterator in interface java.util.List<E>
        Overrides:
        listIterator in class java.util.ArrayList<E>
        Returns:
        a java.util.ListIterator that cannot modify this ArrayList-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 ArrayList 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 ArrayList) would provide a potential back-door for breaking the Immutable-Contract of the ReadOnlyArrayList 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 ArrayList-Builder will, instead, throw a Java UnsupportedOperationException.
        Specified by:
        subList in interface java.util.List<E>
        Overrides:
        subList in class java.util.ArrayList<E>
        Returns:
        a java.util.List that cannot modify this ArrayList-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 original class java.util.ArrayList. Ignores the private field 'built'. If 'this' has not been built, but 'o' has been, that fact is ignored during the equality-comparison.
        Specified by:
        equals in interface java.util.Collection<E>
        Specified by:
        equals in interface java.util.List<E>
        Overrides:
        equals in class java.util.ArrayList<E>
        Parameters:
        o - object to be compared for equality with this ROArrayListBuilder instance
        Returns:
        true if the specified Object is equal to this Builder
        Code:
        Exact Method Body:
         if (this == o) return true;
 if (! (o instanceof ROArrayListBuilder)) return false;
 return super.equals((ArrayList) o);

      • clone

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

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