/*
* Copyright (c) 1997, 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 Torello.Java.Additional.RemoveUnsupportedIterator;

import java.util.function.*;

import java.util.*;

import java.util.stream.Collector;

import java.io.Serializable;

/**
 * Immutable Wrapper for <CODE>java&#46;util&#46;ArrayList</CODE>, found in the "Java Collections
 * Framework".
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=ArrayList>
 * <EMBED CLASS='external-html' DATA-FILE-ID=MUCHOS_CONSTRUCTORS>
 * <EMBED CLASS='external-html' DATA-FILE-ID=DATA_CLASS>
 * 
 * @param <E> the type of elements in this list
 */
@SuppressWarnings("unchecked")
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_MAIN")
public class ReadOnlyArrayList<E> implements ReadOnlyList<E>, RandomAccess, Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Protected & Private Fields, Methods, Statics
    // ********************************************************************************************
    // ********************************************************************************************


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

    // Minor Optimization where new ArrayList's that have no contents always re-use this static
    // instance.  Since this instance is completely empty, the Raw-Types things is irrelevant.

    @SuppressWarnings("rawtypes")
    private static final ArrayList EMPTY_ARRAY_LIST = new ArrayList(0);

    // Singleton & Empty ReadOnlyArrayList, Uses the "Supplier Constructor"
    @SuppressWarnings("rawtypes")
    private static final ReadOnlyArrayList EMPTY_READONLY_ARRAY_LIST =
        new ReadOnlyArrayList(0, () -> null);

    // The actual ArrayList used by this instance.
    private final ArrayList<E> arrayList;

    // TRUE     => This was built using the class ROArrayListBuilder
    // FALSE    => This was built using the clone() of a standard java.util.ArrayList constructor

    private final boolean fromBuilderOrArrayList;

    // Mimics the C++ Keyword/Concept of "Friend Class".   Is "Friends With" ROArrayListBuilder
    static class AccessBadge { private AccessBadge() { } }
    private static final AccessBadge friendClassBadge = new AccessBadge();

    public static <T> ReadOnlyArrayList<T> emptyROAL()
    { return (ReadOnlyArrayList<T>) EMPTY_READONLY_ARRAY_LIST; }


    // ********************************************************************************************
    // ********************************************************************************************
    // Basic Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    // To all the readers out there following along: The "AccessBadge" thing is just a slightly
    // wimpier substitute for the C++ keyword / concept 'friend' or "Friend Class".  It means this
    // constructor is (for all intents and purposes) a private-constructor, except for the class
    // ROArrayListBuilder
    //
    // This is the Constructor used by the Builder.  It has a "Zero-Size" Optimization

    ReadOnlyArrayList(ROArrayListBuilder<E> roalb, ROArrayListBuilder.AccessBadge badge)
    {
        Objects.requireNonNull(badge, "Access Badge is null.  Requires Friend-Class Badge");

        fromBuilderOrArrayList = true;
        this.arrayList = roalb;
    }

    /**
     * Copies parameter {@code 'c'} (and saves it) in order to guarantee that {@code 'this'}
     * instance is Read-Only, and shielded from outside modification.
     * 
     * @param c The {@code Collection} to be copied and saved into this instance internal
     * and private {@code 'arrayList'} field.
     */
    public ReadOnlyArrayList(Collection<E> c)
    {
        fromBuilderOrArrayList = false;

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (c.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : new ArrayList<>(c);
    }

    /**
     * Use a {@code Supplier<E>} to provide an arbitrary number of elements of type {@code 'E'} 
     * directly to this constructor.  This constructor will request elements from the
     * {@code Supplier} provided to parameter {@code 's'} until {@code 's'} returns null.
     *
     * <EMBED CLASS=defs DATA-SOURCE=Supplier>
     * 
     * @param quantityIfKnown <EMBED CLASS='external-html' DATA-FILE-ID=VECAL_INIT_CAPACITY>
     * @param s Any Java {@code Supplier<E>}
     * @throws IllegalArgumentException if the specified quantity / capacity is negative
     */
    public ReadOnlyArrayList(Integer quantityIfKnown, Supplier<E> s)
    {
        fromBuilderOrArrayList = false;

        ArrayList<E> arrayList = (quantityIfKnown != null)
            ? new ArrayList<>(quantityIfKnown)
            : new ArrayList<>();

        E e;
        while ((e = s.get()) != null) arrayList.add(e);

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (arrayList.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : arrayList;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Iterable & Array Based Constructors - **NO FILTER**
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * If only a small amount of processing needs to be done on the contents of some Java
     * Data-Type, and using an entire Builder-Class seems disproportionately complex - <I>this
     * constructor can convert any Java {@code Iterable} into a {@code ReadOnlyArrayList}, using
     * a simple {@code 'mapper'}</I>.
     * 
     * <EMBED CLASS=defs DATA-SOURCE=Iterable>
     * 
     * @param <T>           <EMBED CLASS='external-html' DATA-FILE-ID=ITERABLE_TYPE_PARAM>
     * @param i             Any Java {@code Iterable<T>}
     * @param mapper        <EMBED CLASS='external-html' DATA-FILE-ID=ITERABLE_MAPPER>
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=VECAL_INIT_CAPACITY>
     * 
     * @throws NullPointerException if either {@code 'i'} or {@code 'mapper'} are passed null
     */
    public <T> ReadOnlyArrayList(
            Iterable<T> i,
            Function<? super T, ? extends E> mapper,
            Integer sizeIfKnown)
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

        fromBuilderOrArrayList = false;

        ArrayList<E> arrayList = (sizeIfKnown != null)
            ? new ArrayList<>(sizeIfKnown)
            : new ArrayList<>();

        for (T t : i) arrayList.add(mapper.apply(t));

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (arrayList.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : arrayList;
    }

    /**
     * If a Standard Java {@code Iterable} can be directly mapped into an {@code ArrayList}
     * (and, ergo, an entire Builder-Instance would be a bit excessive) - <I>this constructor will
     * seamlessly convert any Java {@code Iterable<E>} directly into a {@code ReadOnlyArrayList<E>}
     * with just this single invocation</I>.
     *
     * <EMBED CLASS=defs DATA-SOURCE=Iterable>
     * 
     * @param i             Any Java {@code Iterable<E>}
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=VECAL_INIT_CAPACITY>
     * 
     * @throws IllegalArgumentException if the specified initial capacity is negative
     */
    public ReadOnlyArrayList(Iterable<E> i, Integer sizeIfKnown)
    {
        fromBuilderOrArrayList = false;

        ArrayList<E> arrayList = (sizeIfKnown != null)
            ? new ArrayList<>(sizeIfKnown)
            : new ArrayList<>();

        for (E element : i) arrayList.add(element);

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (arrayList.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : arrayList;
    }

    /**
     * Builds {@code ReadOnlyArrayList<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param elementsType  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_TYPE>
     * @param elements      <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws ClassCastException   <EMBED CLASS='external-html' DATA-FILE-ID=CCEX>
     * @throws NullPointerException If {@code 'elementsType'} is passed null.
     */
    public ReadOnlyArrayList(Class<E> elementsType, Object... elements)
    {
        Objects.requireNonNull(elementsType, ROHelpers.NULL_MSG + "'elementsType'");

        fromBuilderOrArrayList = false;

        if (elements.length == 0)
            this.arrayList = (ArrayList<E>) EMPTY_ARRAY_LIST;

        else 
        {
            this.arrayList = new ArrayList<>(elements.length);
            for (Object element : elements) this.arrayList.add(elementsType.cast(element));
        }
    }

    /**
     * Builds {@code ReadOnlyArrayList<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param mapper    <EMBED CLASS='external-html' DATA-FILE-ID=OBJ_E_MAPPER>
     * @param elements  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws ClassCastException   <EMBED CLASS='external-html' DATA-FILE-ID=CCEX>
     * @throws NullPointerException If {@code 'mapper'} is passed null.
     */
    public ReadOnlyArrayList(Function<Object, ? extends E> mapper, Object... elements)
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

        fromBuilderOrArrayList = false;

        if (elements.length == 0)
            this.arrayList = (ArrayList<E>) EMPTY_ARRAY_LIST;

        else 
        {
            this.arrayList = new ArrayList<>(elements.length);
            for (Object element : elements) this.arrayList.add(mapper.apply(element));
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Iterable & Array Based Constructors - **INCLUDES ELEMENT FILTER**
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * If only a small amount of processing needs to be done on the contents of some Java
     * Data-Type, and using an entire Builder-Class seems disproportionately complex - <I>this
     * constructor can convert any Java {@code Iterable} into a {@code ReadOnlyArrayList}, using
     * a simple {@code 'mapper'}</I>.
     * 
     * <EMBED CLASS=defs DATA-SOURCE=Iterable>
     * 
     * @param <T>           <EMBED CLASS='external-html' DATA-FILE-ID=ITERABLE_TYPE_PARAM>
     * @param i             Any Java {@code Iterable<T>}
     * @param mapper        <EMBED CLASS='external-html' DATA-FILE-ID=ITERABLE_MAPPER>
     * @param filter        <EMBED CLASS='external-html' DATA-FTP=T DATA-FILE-ID=PREDICATE_FILTER>
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=VECAL_INIT_CAPACITY>
     * 
     * @throws NullPointerException if any of {@code 'i'}, {@code 'mapper'} or {@code 'filter'}
     * are passed null.
     */
    public <T> ReadOnlyArrayList(
            Iterable<T>                         i,
            Function<? super T, ? extends E>    mapper,
            Predicate<? super T>                filter,
            Integer                             sizeIfKnown
        )
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrArrayList = false;

        ArrayList<E> arrayList = (sizeIfKnown != null)
            ? new ArrayList<>(sizeIfKnown)
            : new ArrayList<>();

        for (T t : i) if (filter.test(t)) arrayList.add(mapper.apply(t));

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (arrayList.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : arrayList;
    }

    /**
     * If a Standard Java {@code Iterable} can be directly mapped into an {@code ArrayList}
     * (and, ergo, an entire Builder-Instance would be a bit excessive) - <I>this constructor will
     * seamlessly convert any Java {@code Iterable<E>} directly into a {@code ReadOnlyArrayList<E>}
     * with just this single invocation</I>.
     *
     * <EMBED CLASS=defs DATA-SOURCE=Iterable>
     * 
     * @param i             Any Java {@code Iteratable<E>}
     * @param filter        <EMBED CLASS='external-html' DATA-FTP=E DATA-FILE-ID=PREDICATE_FILTER>
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=VECAL_INIT_CAPACITY>
     * 
     * @throws IllegalArgumentException if the specified initial capacity is negative
     * @throws NullPointerException     if either {'i'} or {@code 'filter'} are passed null
     */
    public ReadOnlyArrayList(Iterable<E> i, Predicate<? super E> filter, Integer sizeIfKnown)
    {
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrArrayList = false;

        ArrayList<E> arrayList = (sizeIfKnown != null)
            ? new ArrayList<>(sizeIfKnown)
            : new ArrayList<>();

        for (E element : i) if (filter.test(element)) arrayList.add(element);

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (arrayList.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : arrayList;
    }

    /**
     * Builds {@code ReadOnlyArrayList<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param elementsType  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_TYPE>
     * @param filter        <EMBED CLASS='external-html' DATA-FTP=E DATA-FILE-ID=PREDICATE_FILTER>
     * @param elements      <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws ClassCastException <EMBED CLASS='external-html' DATA-FILE-ID=CCEX>
     * 
     * @throws NullPointerException If either {@code 'elementsType'} or {@code 'filter'} are
     * passsed null.
     */
    public ReadOnlyArrayList
        (Class<E> elementsType, Predicate<? super E> filter, Object... elements)
    {
        Objects.requireNonNull(elementsType, ROHelpers.NULL_MSG + "'elementsType'");
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrArrayList = false;

        ArrayList<E> arrayList = new ArrayList<>(elements.length);

        E e;
        for (Object element : elements)
            if (filter.test(e = elementsType.cast(element)))
                arrayList.add(e);

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (arrayList.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : arrayList;
    }

    /**
     * Builds {@code ReadOnlyArrayList<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param mapper    <EMBED CLASS='external-html' DATA-FILE-ID=OBJ_E_MAPPER>
     * @param filter    <EMBED CLASS='external-html' DATA-FTP=Object DATA-FILE-ID=PREDICATE_FILTER>
     * @param elements  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws NullPointerException If either {@code 'mapper'} or {@code 'filter'} are passed null
     */
    public ReadOnlyArrayList
        (Function<Object, ? extends E> mapper, Predicate<Object> filter, Object... elements)
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrArrayList = false;

        ArrayList<E> arrayList = new ArrayList<>(elements.length);

        for (Object element : elements)
            if (filter.test(element))
                arrayList.add(mapper.apply(element));

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (arrayList.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : arrayList;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // @SafeVarargs / Variable-Arity / VarArgs: with Parameterized / Generic Type's
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Builds {@code ReadOnlyArrayList<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param elements <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     */
    @SafeVarargs
    public ReadOnlyArrayList(E... elements)
    {
        fromBuilderOrArrayList = false;

        if (elements.length == 0)
            this.arrayList = (ArrayList<E>) EMPTY_ARRAY_LIST;

        else 
        {
            this.arrayList = new ArrayList<>(elements.length);
            for (E e : elements) this.arrayList.add(e);
        }
    }

    /**
     * Builds {@code ReadOnlyArrayList<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param <T>       <EMBED CLASS='external-html' DATA-FILE-ID=VARARGS_TYPE_PARAM>
     * @param dummy     <EMBED CLASS='external-html' DATA-FILE-ID=DUMMY_INT>
     * @param mapper    <EMBED CLASS='external-html' DATA-FILE-ID=T_ARR_E_MAPPER>
     * @param elements  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws NullPointerException If {@code 'mapper'} is passed null.
     */
    @SafeVarargs
    public <T> ReadOnlyArrayList(
            int                                 dummy,
            Function<? super T, ? extends E>    mapper,
            T...                                elements
        )
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

        fromBuilderOrArrayList = false;

        if (elements.length == 0)
            this.arrayList = (ArrayList<E>) EMPTY_ARRAY_LIST;

        else 
        {
            this.arrayList = new ArrayList<>(elements.length);
            for (T t : elements) this.arrayList.add(mapper.apply(t));
        }
    }

    /**
     * Builds {@code ReadOnlyArrayList<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param filter    <EMBED CLASS='external-html' DATA-FTP=E DATA-FILE-ID=PREDICATE_FILTER>
     * @param elements  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws NullPointerException If {@code 'filter'} is passsed null.
     */
    @SafeVarargs
    public ReadOnlyArrayList(Predicate<? super E> filter, E... elements)
    {
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrArrayList = false;

        ArrayList<E> arrayList = new ArrayList<>(elements.length);
        for (E e : elements) if (filter.test(e)) arrayList.add(e);

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (arrayList.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : arrayList;
    }

    /**
     * Builds {@code ReadOnlyArrayList<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param <T>       <EMBED CLASS='external-html' DATA-FILE-ID=VARARGS_TYPE_PARAM>
     * @param filter    <EMBED CLASS='external-html' DATA-FTP=T DATA-FILE-ID=PREDICATE_FILTER>
     * @param mapper    <EMBED CLASS='external-html' DATA-FILE-ID=T_ARR_E_MAPPER>
     * @param elements  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws NullPointerException If either {@code 'mapper'} or {@code 'filter'} are passed null
     */
    @SafeVarargs
    public <T> ReadOnlyArrayList(
            Predicate<? super T>                filter,
            Function<? super T, ? extends E>    mapper,
            T...                                elements
        )
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrArrayList = false;

        ArrayList<E> arrayList = new ArrayList<>(elements.length);
        for (T t : elements) if (filter.test(t)) arrayList.add(mapper.apply(t));

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (arrayList.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : arrayList;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // PRIMITIVE-ARRAY INPUT
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Converts a Java Primitive-Array to a {@code ReadOnlyArrayList<E>}, where {@code 'E'} is the
     * Java Boxed-Type which corresponds to the Primitive-Array's Type.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CTOR_DESC>
     * @param primitiveArray        <EMBED CLASS='external-html' DATA-FILE-ID=PRIMITIVE_ARRAY>
     * @throws ClassCastException   <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CCEX>
     * @throws NullPointerException If {@code 'primitiveArray'} is passed null;
     */
    public ReadOnlyArrayList(Object primitiveArray)
    {
        fromBuilderOrArrayList = false;

        ArrayList<E> al = ROHelpers.buildROListOrSet(
            primitiveArray,
            (int arrayLen) -> new ArrayList<E>(arrayLen),
            null
        );

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (al.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : al;
    }

    /**
     * Converts a Java Primitive-Array to a {@code ReadOnlyArrayList<E>}, where {@code 'E'} is the
     * Java Boxed-Type which corresponds to the Primitive-Array's Type - <I>but also accepts a 
     * {@code 'filter'} that can remove any array-entries that need to be removed</I>.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CTOR_DESC>
     * @param primitiveArray        <EMBED CLASS='external-html' DATA-FILE-ID=PRIMITIVE_ARRAY>
     * @param filter                <EMBED CLASS='external-html' DATA-FILE-ID=PRED_FILT_PRIM>
     * @throws ClassCastException   <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CCEX>
     * @throws NullPointerException If {@code 'primitiveArray'} is passed null;
     */
    public ReadOnlyArrayList(
            Object          primitiveArray,
            Predicate<?>    filter
        )
    {
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrArrayList = false;

        ArrayList<E> al = ROHelpers.buildROListOrSet(
            primitiveArray,
            (int arrayLen) -> new ArrayList<E>(arrayLen),
            filter
        );

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.arrayList = (al.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : al;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.util.stream.Stream HELPER
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * For use with a the Java Stream method {@code 'collect(Collector c)'}.
     * 
     * <EMBED CLASS='external-html' DATA-ABBREV=al DATA-FILE-ID=STREAM_COLLECTOR>
     * 
     * @param <T> This is the Generic-Type of the Input-Stream.  It will also be the Generic-Type
     * of the {@code ReadOnlyArrayList} that's returned from the stream's {@code collect} method.
     * 
     * @param characteristics Optional Characteristics List.  See Java Stream-API Documentation on
     * {@code Collector.Characteristics} inner-class for more details.
     * 
     * @return This returns a collector that may be piped into a stream's {@code 'collect'} method,
     * as in the example, above.
     */
    public static <T> java.util.stream.Collector
        <T, ROArrayListBuilder<T>, ReadOnlyArrayList<T>>
        streamCollector(Collector.Characteristics... characteristics)
    {
        return Collector.of(
            ROArrayListBuilder<T>::new,    // The "Supplier"    (builds a new ROArrayListBuilder)
            ROArrayListBuilder<T>::add,    // The "Accumulator" (adds elements to the builder)

            // Oracle Making Life Difficult - It should be the line below, but, alas, it is not!
            // ROArrayListBuilder<T>::addAll, // The "Combiner" (combines two  ROArrayListBuilders)
            //
            // In Stream.collect(), the 3rd parameter - the "combiner" - is a "BiConsumer<R, R>"
            // NOTE: A "BiConsumer" is a FunctionalInterface that does not return anything - it is
            // (obviously) a "void" return method!
            //
            // **BUT**
            //
            // In Collector.of, the 3rd parameter - the "combiner" - is a "BinaryOperation<R>"

            (ROArrayListBuilder<T> roalb1, ROArrayListBuilder<T> roalb2) ->
            {
                roalb1.addAll(roalb2);
                return roalb1;
            },

            ROArrayListBuilder<T>::build,  // The "Finisher"    (Converts Builder to ReadOnlyArrayList)
            characteristics
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Convert to java.util Types
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Clone's {@code 'this'} instance internal {@code ArrayList<E>} field, and returns it. 
     * <EMBED CLASS='external-html' DATA-TYPE=ArrayList DATA-FILE-ID=CLONE_TO>
     * 
     * @return An independent, mutable copy of {@code 'this'} instance' internal
     * {@code ArrayList<E>} data-structure.
     */
    public ArrayList<E> cloneToArrayList()
    {
        return fromBuilderOrArrayList
            ? new ArrayList<E>(this.arrayList)
            : (ArrayList<E>) this.arrayList.clone();
    }

    /**
     * Invokes {@code java.util.Collections.unmodifiableList} on the internal {@code ArrayList}.
     * <EMBED CLASS='external-html' DATA-RET_TYPE=List DATA-FILE-ID=WRAP_TO_IMMUTABLE>
     * 
     * @return A {@code List} which adheres to the JDK interface {@code java.util.List}, but throws
     * an {@code UnsupportedOperationException} if a user attempts to invoke a Mutator-Method on
     * the returned instance.
     */
    public List<E> wrapToImmutableList()
    { return Collections.unmodifiableList(this.arrayList); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Methods, java.util.ArrayList
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns the number of elements in this list.
     * @return the number of elements in this list
     */
    public int size()
    { return this.arrayList.size(); }

    /**
     * Returns {@code TRUE} if this list contains no elements.
     * @return {@code TRUE} if this list contains no elements
     */
    public boolean isEmpty()
    { return this.arrayList.isEmpty(); }

    /**
     * Returns {@code TRUE} if this list contains the specified element.  More formally, returns
     * {@code TRUE} if and only if this list contains at least one element {@code e} such that
     * {@code Objects.equals(o, e)}.
     *
     * @param o element whose presence in this list is to be tested
     * @return {@code TRUE} if this list contains the specified element
     */
    public boolean contains(Object o)
    { return this.arrayList.contains(o); }

    /**
     * Returns the index of the first occurrence of the specified element in this list, or
     * {@code -1} if this list does not contain the element.  More formally, returns the lowest
     * index {@code i} such that {@code Objects.equals(o, get(i))}, or {@code -1} if there is no
     * such index.
     */
    public int indexOf(Object o)
    { return this.arrayList.indexOf(o); }

    /**
     * Returns the index of the last occurrence of the specified element in this list, or
     * {@code -1} if this list does not contain the element.  More formally, returns the highest
     * index {@code i} such that {@code Objects.equals(o, get(i))}, or {@code -1} if there is no
     * such index.
     */
    public int lastIndexOf(Object o)
    { return this.arrayList.lastIndexOf(o); }

    /**
     * Returns an array containing all of the elements in this list in proper sequence (from first
     * to last element).
     *
     * <BR /><BR />The returned array will be "safe" in that no references to it are maintained by
     * this list.  (In other words, this method must allocate a new array).  The caller is thus
     * free to modify the returned array.
     *
     * <BR /><BR />This method acts as bridge between array-based and collection-based APIs.
     *
     * @return an array containing all of the elements in this list in proper sequence
     */
    public Object[] toArray()
    { return this.arrayList.toArray(); }

    /**
     * Returns an array containing all of the elements in this list in proper sequence (from first
     * to last element); the runtime type of the returned array is that of the specified array.  If
     * the list fits in the specified array, it is returned therein.  Otherwise, a new array is
     * allocated with the runtime type of the specified array and the size of this list.
     *
     * <BR /><BR />If the list fits in the specified array with room to spare (i.e., the array has
     * more elements than the list), the element in the array immediately following the end of the
     * collection is set to {@code null}.  (This is useful in determining the length of the list
     * <i>only</i> if the caller knows that the list does not contain any null elements.)
     *
     * @param a the array into which the elements of the list are to be stored, if it is big enough;
     * otherwise, a new array of the same runtime type is allocated for this purpose.
     * 
     * @return an array containing the elements of the list
     * 
     * @throws ArrayStoreException if the runtime type of the specified array is not a supertype of
     * the runtime type of every element in this list
     * 
     * @throws NullPointerException if the specified array is null
     */
    public <T> T[] toArray(T[] a)
    { return this.arrayList.toArray(a); }

    /**
     * Returns the element at the specified position in this list.
     * @param  index index of the element to return
     * @return the element at the specified position in this list
     * @throws IndexOutOfBoundsException {@inheritDoc}
     */
    public E get(int index)
    { return this.arrayList.get(index); }

    /** @throws NullPointerException {@inheritDoc} */
    @Override
    public void forEach(Consumer<? super E> action)
    { this.arrayList.forEach(action); }

    /**
     * Utilizes this class private, internal {@code 'arrayList'} field to generate a
     * {@code Spliterator}.
     * 
     * @return a {@code Spliterator} over the elements in this list
     */
    @Override
    public Spliterator<E> spliterator()
    { return this.arrayList.spliterator(); }


    // ********************************************************************************************
    // ********************************************************************************************
    // The Builder AccessDenied Issue
    // ********************************************************************************************
    // ********************************************************************************************


   /**
    * Returns a list iterator over the elements in this list (in proper sequence), starting at the
    * specified position in the list.  The specified index indicates the first element that would
    * be returned by an initial call to {@link ReadOnlyListIterator#next next}.  An initial call to
    * {@link ReadOnlyListIterator#previous previous} would return the element with the specified
    * index minus one.
    *
    * @throws IndexOutOfBoundsException {@inheritDoc}
    */
    public ReadOnlyListIterator<E> listIterator(int index)
    {
        return InterfaceBuilder.toReadOnlyListIterator(
            fromBuilderOrArrayList 
                ? ((ROArrayListBuilder<E>) this.arrayList)._listIterator(index, friendClassBadge)
                : this.arrayList.listIterator(index)
        );
    }

    /**
     * Returns a list iterator over the elements in this list (in proper sequence).
     * @see #listIterator(int)
     */
    public ReadOnlyListIterator<E> listIterator()
    {
        return InterfaceBuilder.toReadOnlyListIterator(
            fromBuilderOrArrayList 
                ? ((ROArrayListBuilder<E>) this.arrayList)._listIterator(friendClassBadge)
                : this.arrayList.listIterator()
        );
    }

    /**
     * Returns an iterator over the elements in this list in proper sequence.
     * @return an iterator over the elements in this list in proper sequence
     */
    public RemoveUnsupportedIterator<E> iterator()
    {
        return fromBuilderOrArrayList
            ? (RemoveUnsupportedIterator<E>) this.arrayList.iterator()
            : new RemoveUnsupportedIterator<E>(this.arrayList.iterator());
    }

    /**
     * Returns a view of the portion of this list between the specified {@code 'fromIndex'},
     * inclusive, and {@code toIndex}, exclusive.  (If {@code 'fromIndex'} and {@code 'toIndex'}
     * are equal, the returned list is empty.) 
     * 
     * @throws IndexOutOfBoundsException {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    public ReadOnlyList<E> subList(int fromIndex, int toIndex)
    {
        return InterfaceBuilder.toReadOnlyList(
            fromBuilderOrArrayList 
                ? ((ROArrayListBuilder<E>) this.arrayList).
                    _subList(fromIndex, toIndex, friendClassBadge)
                : this.arrayList.subList(fromIndex, toIndex)
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Methods, java.util.AbstractList
    // ********************************************************************************************
    // ********************************************************************************************


    public boolean containsAll(Collection<?> c)
    { return this.arrayList.containsAll(c); }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a {@code String} representation of this {@code ArrayList}. The {@code String}
     * representation consists of a list of the collection's elements in the order they are
     * returned by its iterator, enclosed in square brackets ({@code "[]"}). Adjacent elements are
     * separated by the characters {@code ", "} (comma and space). Elements are converted to
     * {@code String's} as by {@code String.valueOf(Object)}.
     * 
     * @return a {@code String} representation of this {@code ArrayList}
     */
    public String toString()
    { return this.arrayList.toString(); }

    /**
     * Compares the specified Object with this List for equality, as per the definition in the 
     * class {@code java.util.ArrayList}.
     *
     * @param  o object to be compared for equality with this {@code ReadOnlyArrayList}
     * @return {@code TRUE} if the specified Object is equal to this List
     */
    public boolean equals(Object o)
    { return ROHelpers.roListEq(this, o); }

    /**
     * Returns the hash code value for this List as per the definition in the class
     * {@code java.util.ArrayList}.
     */
    public int hashCode()
    { return this.arrayList.hashCode(); }
}