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

import java.io.Serializable;
import java.util.function.Predicate;

import java.util.*;

import Torello.Java.Additional.RemoveUnsupportedIterator;


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


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

    // Exception messages need this
    private static final String ROTS = "TreeSet";

    private boolean built = false;

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

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

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

        return (size() == 0)
            ? ReadOnlyTreeSet.emptyROTS()
            : new ReadOnlyTreeSet<E>(this, friendClassBadge);
    }


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


    /**
     * Constructs a new, empty tree set, sorted according to the natural ordering of its elements.
     * All elements inserted into the set must implement the {@code Comparable} interface.
     * Furthermore, all such elements must be <i>mutually comparable</i>: {@code e1.compareTo(e2)}
     * must not throw a {@code ClassCastException} for any elements {@code e1} and {@code e2} in
     * the set.  If the user attempts to add an element to the set that violates this constraint
     * (for example, the user attempts to add a string element to a set whose elements are
     * integers), the {@code add} call will throw a {@code ClassCastException}.
     */
    public ROTreeSetBuilder()
    { super(); }

    /**
     * Constructs a new, empty tree set, sorted according to the specified comparator.  All
     * elements inserted into the set must be <i>mutually comparable</i> by the specified
     * comparator: {@code comparator.compare(e1, e2)} must not throw a {@code ClassCastException}
     * for any elements {@code e1} and {@code e2} in the set.  If the user attempts to add an
     * element to the set that violates this constraint, the {@code add} call will throw a
     * {@code ClassCastException}.
     *
     * @param comparator the comparator that will be used to order this set.  If {@code null}, the
     * {@linkplain Comparable natural ordering} of the elements will be used.
     */
    public ROTreeSetBuilder(Comparator<? super E> comparator)
    { super(comparator); }

    /**
     * Constructs a new tree set containing the elements in the specified collection, sorted
     * according to the <i>natural ordering</i> of its elements.  All elements inserted into the
     * set must implement the {@link Comparable} interface.  Furthermore, all such elements must be
     * <i>mutually comparable</i>: {@code e1.compareTo(e2)} must not throw a
     * {@code ClassCastException} for any elements {@code e1} and {@code e2} in the set.
     *
     * @param c collection whose elements will comprise the new set
     * 
     * @throws ClassCastException if the elements in {@code c} are not {@link Comparable}, or are
     * not mutually comparable
     * 
     * @throws NullPointerException if the specified collection is null
     */
    public ROTreeSetBuilder(Collection<? extends E> c)
    { super(c); }

    /**
     * Constructs a new tree set containing the same elements and using the same ordering as the
     * specified sorted set.
     *
     * @param s sorted set whose elements will comprise the new set
     * @throws NullPointerException if the specified sorted set is null
     */
    public ROTreeSetBuilder(SortedSet<E> s)
    { super(s); }


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


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

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

    /**
     * Adds the specified element to this set if it is not already present.  More formally, adds
     * the specified element {@code e} to this set if the set contains no element {@code e2} such
     * that {@code Objects.equals(e, e2)}.  If this set already contains the element, the call
     * leaves the set unchanged and returns {@code FALSE}.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param e element to be added to this set
     * @return {@code TRUE} if this set did not already contain the specified element
     * 
     * @throws ClassCastException if the specified object cannot be compared with the elements
     * currently in this set
     * 
     * @throws NullPointerException if the specified element is null and this set uses natural
     * ordering, or its comparator does not permit null elements
     */
    public boolean add(E e)
    {
        if (this.built) throw new AttemptedModificationException(ROTS);
        return super.add(e); 
    }

    /**
     * Removes the specified element from this set if it is present.  More formally, removes an
     * element {@code e} such that {@code Objects.equals(o, e)}, if this set contains such an
     * element.  Returns {@code TRUE} if this set contained the element (or equivalently, if this
     * set changed as a result of the call).  (This set will not contain the element once the call
     * returns.)
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * 
     * @param o object to be removed from this set, if present
     * @return {@code TRUE} if this set contained the specified element
     * 
     * @throws ClassCastException if the specified object cannot be compared with the elements
     * currently in this set
     * 
     * @throws NullPointerException if the specified element is null and this set uses natural
     * ordering, or its comparator does not permit null elements
     */
    public boolean remove(Object o)
    {
        if (this.built) throw new AttemptedModificationException(ROTS);
        return super.remove(o); 
    }

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

    /**
     * Adds all of the elements in the specified collection to this set.
     * 
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param c collection containing elements to be added to this set
     * @return {@code TRUE} if this set changed as a result of the call
     * 
     * @throws ClassCastException if the elements provided cannot be compared with the elements
     * currently in the set
     * 
     * @throws NullPointerException if the specified collection is null or if any element is null
     * and this set uses natural ordering, or its comparator does not permit null elements
     */
    public  boolean addAll(Collection<? extends E> c)
    {
        if (this.built) throw new AttemptedModificationException(ROTS);
        return super.addAll(c); 
    }

    /**
     * Retrieves and removes the first (lowest) element, or returns null if this set is empty.
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * @return the first element, or null if this set is empty
     */
    public E pollFirst()
    {
        if (this.built) throw new AttemptedModificationException(ROTS);
        return super.pollFirst(); 
    }

    /**
     * Retrieves and removes the last (highest) element, or returns null if this set is empty.
     * <EMBED DATA-TYPE=TreeMap CLASS='external-html' DATA-FILE-ID=MUTATOR>
     * @return the last element, or null if this set is empty
     */
    public E pollLast()
    {
        if (this.built) throw new AttemptedModificationException(ROTS);
        return super.pollLast(); 
    }


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


    // ceiling, comparator, contains, descendingIterator, descendingSet, first, floor, headSet,
    // headSet, higher, isEmpty, iterator, last, lower, size, spliterator, subSet, subSet, tailSet,
    // tailSet
    // 
    // Introspection Only: ceiling, comparator, contains, first, floor, isEmpty, higher, isEmpty,
    //                     last, lower, size, spliterator, 
    //
    // Mutator or Possible Mutator: descendingIterator, descendingSet, headSet, headSet, iterator,
    //                              subSet, subSet, tailSet, tailSet
    //
    // Methods inherited from class java.util.AbstractSet:
    // hashCode, removeAll
    // 
    // Methods inherited from class java.util.AbstractCollection:
    // containsAll, retainAll, toArray, toArray, toString
    // 
    // Methods inherited from interface java.util.Collection:
    // parallelStream, removeIf, stream, toArray
    // 
    // Methods inherited from interface java.lang.Iterable:
    // forEach
    //
    // Methods inherited from interface java.util.Set
    // containsAll, hashCode, removeAll, retainAll, toArray, toArray

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

    NavigableSet<E> _descendingSet(ReadOnlyTreeSet.AccessBadge friendClassBadge)
    { return super.descendingSet(); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=SortedSet DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.SortedSet} that cannot modify this {@code TreeSet-Builder}
     */
    public SortedSet<E> headSet(E toElement)
    { return Collections.unmodifiableSortedSet(super.headSet(toElement, false)); }

    // *** Java-HTML: 
    // Looking at the JDK-21 Code for TreeMap, headSet(E toElem) just calls headSet(E, boolean)
    // This supbstitution has to happen, or else the AccessDeniedException throws

    SortedSet<E> _headSet(E toElement, ReadOnlyTreeSet.AccessBadge friendClassBadge)
    { return super.headSet(toElement, false); /* Java-HTML: was headSet(toElement) */ }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=NavigableSet DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.NavigableSet} that cannot modify this {@code TreeSet-Builder}
     */
    public NavigableSet<E> headSet(E toElement, boolean inclusive)
    { return Collections.unmodifiableNavigableSet(super.headSet(toElement, inclusive)); }

    NavigableSet<E> _headSet
        (E toElement, boolean inclusive, ReadOnlyTreeSet.AccessBadge friendClassBadge)
    { return super.headSet(toElement, inclusive); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=NavigableSet DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.NavigableSet} that cannot modify this {@code TreeSet-Builder}
     */
    public NavigableSet<E> subSet
        (E fromElement, boolean fromInclusive, E toElement, boolean toInclusive)
    {
        return Collections.unmodifiableNavigableSet
            (super.subSet(fromElement, fromInclusive, toElement, toInclusive));
    }

    NavigableSet<E> _subSet(
            E fromElement, boolean fromInclusive, E toElement, boolean toInclusive,
            ReadOnlyTreeSet.AccessBadge friendClassBadge
        )
    { return super.subSet(fromElement, fromInclusive, toElement, toInclusive); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=SortedSet DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.SortedSet} that cannot modify this {@code TreeSet-Builder}
     */
    public SortedSet<E> subSet(E fromElement, E toElement)
    {
        return Collections.unmodifiableSortedSet
            (super.subSet(fromElement, true, toElement, false));
    }

    // *** Java-HTML: 
    // Looking at the JDK-21 Code for TreeMap, subSet(E fromElement, E toElem) just calls
    //      subSet(E, boolean, E, boolean)
    // This supbstitution has to happen, or else the AccessDeniedException throws

    SortedSet<E> _subSet(E fromElement, E toElement, ReadOnlyTreeSet.AccessBadge friendClassBadge)
    { return super.subSet(fromElement, true /* added */, toElement, false /* added */); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=NavigableSet DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.NavigableSet} that cannot modify this {@code TreeSet-Builder}
     */
    public NavigableSet<E> tailSet(E fromElement, boolean inclusive)
    { return Collections.unmodifiableNavigableSet(super.tailSet(fromElement, inclusive)); }

    NavigableSet<E> _tailSet
        (E fromElement, boolean inclusive, ReadOnlyTreeSet.AccessBadge friendClassBadge)
    { return super.tailSet(fromElement, inclusive); }

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=SortedSet DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.SortedSet} that cannot modify this {@code TreeSet-Builder}
     */
    public SortedSet<E> tailSet(E fromElement)
    { return Collections.unmodifiableSortedSet(super.tailSet(fromElement, true)); }

    // *** Java-HTML: 
    // Looking at the JDK-21 Code for TreeMap, tailSet(E toElem) just calls tailSet(E, boolean)
    // This supbstitution has to happen, or else the AccessDeniedException throws

    SortedSet<E> _tailSet(E fromElement, ReadOnlyTreeSet.AccessBadge friendClassBadge)
    { return super.tailSet(fromElement, true); /* Java-HTML: was headSet(toElement) */ }


    // ********************************************************************************************
    // ********************************************************************************************
    // More Inherited Methods
    // ********************************************************************************************
    // ********************************************************************************************


    // Copied Directly from the comments listed in the previous section (above)
    // 
    // java.util.AbstractSet:           hashCode, removeAll
    // java.util.AbstractCollection:    containsAll, retainAll, toArray, toArray, toString
    // java.util.Collection:            parallelStream, removeIf, stream, toArray
    // java.lang.Iterable:              forEach
    // java.util.Set:                   containsAll, hashCode, removeAll, retainAll, toArray

    public boolean removeAll(Collection<?> c)
    {
        if (this.built) throw new AttemptedModificationException(ROTS);
        return super.removeAll(c);
    }

    public boolean retainAll(Collection<?> c)
    {
        if (this.built) throw new AttemptedModificationException(ROTS);
        return super.retainAll(c);
    }

    public boolean removeIf(Predicate<? super E> filter)
    {
        if (this.built) throw new AttemptedModificationException(ROTS);
        return super.removeIf(filter);
    }


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


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

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

    private ROTreeSetBuilder(ROTreeSetBuilder<E> rohsb)
    { super(rohsb); this.built=false; }
}