/*
 * Copyright (c) 1997, 2023, 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.*;

import java.util.function.Predicate;

/**
 * A Copy of Java's {@code HashSet} class; used for building a {@link ReadOnlyHashSet}.  Maintains
 * <I>an internal and inaccessible {@code HashSet<E>} instance</I>. 
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=HashSet>
 * <EMBED CLASS='external-html' DATA-A_AN=a DATA-FILE-ID=BUILDERS>
 * 
 * @param <E> the type of elements maintained by this set
 * @see ReadOnlyHashSet
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_BUILDER")
public final class ROHashSetBuilder<E>
    extends HashSet<E>
    implements Cloneable, java.io.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 ROHS = "HashSet";

    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 HashSet} to the 
     * {@code ReadOnlyHashSet} Wrapper-Class.
     * 
     * @return a newly constructed {@code ReadOnlyHashSet} "Wrapper-Class", shielding the
     * internal {@code 'hashSet'} private-field from any modification.
     */
    public ReadOnlyHashSet<E> build()
    {
        this.built = true;

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


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


    /**
     * Constructs a new, empty {@code ROHashSetBuilder}, the underlying {@code HashMap} instance
     * has default initial capacity (16) and load factor (0.75).
     */
    public ROHashSetBuilder()
    { super(); }

    /**
     * Constructs a new {@code ROHashSetBuilder} containing the elements in the specified
     * collection.  The underlying {@code HashMap} is created with default load factor (0.75) and
     * an initial capacity sufficient to contain the elements in the specified collection.
     *
     * @param c the collection whose elements are to be placed into this set
     * @throws NullPointerException if the specified collection is null
     */
    public ROHashSetBuilder(Collection<? extends E> c)
    { super(c); }

    /**
     * Constructs a new, empty {@code ROHashSetBuilder}; the backing {@code HashMap} instance has
     * the specified initial capacity and the specified load factor.
     *
     * <BR /><BR />To create a {@code ROHashSetBuilder} with an initial capacity that accommodates
     * an expected number of elements, use {@link #newROHashSetBuilder(int) newROHashSetBuilder}.
     *
     * @param initialCapacity the initial capacity of the hash map
     * @param loadFactor the load factor of the hash map
     * 
     * @throws IllegalArgumentException if the initial capacity is less than zero, or if the load
     * factor is nonpositive
     */
    public ROHashSetBuilder(int initialCapacity, float loadFactor)
    { super(initialCapacity, loadFactor); }

    /**
     * Constructs a new, empty {@code ROHashSetBuilder}; the backing {@code HashMap} instance has
     * the specified initial capacity and default load factor (0.75).
     *
     * <BR /><BR />To create a {@code ReadOnlyHashSet} with an initial capacity that accommodates
     * an expected number of elements, use {@link #newROHashSetBuilder(int) newROHashSetBuilder}.
     *
     * @param initialCapacity the initial capacity of the hash table
     * @throws IllegalArgumentException if the initial capacity is less than zero
     */
    public ROHashSetBuilder(int initialCapacity)
    { super(initialCapacity); }

    /**
     * Creates a new, empty {@code ROHashSetBuilder} suitable for the expected number of elements.
     * The returned set uses the default load factor of 0.75, and its initial capacity is generally
     * large enough so that the expected number of elements can be added without resizing the set.
     * 
     * @param <T> the type of elements maintained by the new set builder
     * @param numElements the expected number of elements
     * @return the newly created builder
     * @throws IllegalArgumentException if numElements is negative
     */
    public static <T> ROHashSetBuilder<T> newROHashSetBuilder(int numElements)
    {
        if (numElements < 0)
            throw new IllegalArgumentException("Negative number of elements: " + numElements);

        return new ROHashSetBuilder<>(calculateHashMapCapacity(numElements));
    }

    // Copied from JDK-21, java.util.HashMap
    // Calculate initial capacity for HashMap based classes, from expected size and default load
    // factor (0.75).

    private static int calculateHashMapCapacity(int numMappings)
    { return (int) Math.ceil(numMappings / (double) /* DEFAULT_LOAD_FACTOR */ 0.75f); }


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


    public RemoveUnsupportedIterator<E> iterator()
    { return new RemoveUnsupportedIterator<>(super.iterator()); }

    /**
     * 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 this 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=HashSet 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
     */
    public boolean add(E e)
    {
        if (this.built) throw new AttemptedModificationException(ROHS);
        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=HashSet CLASS='external-html' DATA-FILE-ID=MUTATOR>
     *
     * @param o object to be removed from this set, if present
     * @return {@code TRUE} if the set contained the specified element
     */
    public boolean remove(Object o)
    {
        if (this.built) throw new AttemptedModificationException(ROHS);
        return super.remove(o);
    }

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


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


    // contains, isEmpty, size, spliterator
    // 
    // Introspection Only: contains, isEmpty, size, spliterator
    // Mutator or Potential Mutator Methods: NONE
    // 
    // *** OTHER INHERITED METHODS ***
    // 
    // Methods inherited from class java.util.AbstractSet:
    // hashCode, removeAll
    // 
    // Methods inherited from class java.util.AbstractCollection:
    // addAll, 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:
    // addAll, containsAll, hashCode, removeAll, retainAll, toArray, toArray

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

    @Override
    public boolean addAll(Collection<? extends E> c)
    {
        if (this.built) throw new AttemptedModificationException(ROHS);
        return super.addAll(c);
    }

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

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


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


    /**
     * Compares the specified Object with this Builder for equality, as per the definition in the
     * original class {@code java.util.HashSet}.  Ignores the private field {@code 'built'}.  If
     * {@code 'this'} has not been built, but {@code 'o'} has been, that fact is ignored during the
     * equality-comparison.
     *
     * @param  o object to be compared for equality with this {@code ROHashSetBuilder} 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 ROHashSetBuilder)) return false;
        return super.equals((HashSet) o);
    }

    /**
     * Clones this instance' of {@code ROHashSetBuilder}.
     * 
     * <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 ROHashSetBuilder<E> clone()
    { return new ROHashSetBuilder<>(this); }

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