/*
 * Copyright (c) 1995, 2021, 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.util.*;
import java.io.*;

import java.nio.charset.Charset;
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.Function;

/**
 * A Copy of Java's {@code Properties} class; used for building a {@link ReadOnlyProperties}.
 * Maintains <I>an internal and inaccessible {@code Properties} instance</I>.  
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=Properties>
 * <EMBED CLASS='external-html' DATA-A_AN=a DATA-FILE-ID=BUILDERS>
 * @see ReadOnlyProperties
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_BUILDER")
public final class ROPropertiesBuilder
    extends Properties
    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 ROP = "Properties";

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

        return (size() == 0)
            ? ReadOnlyProperties.emptyROP()
            : new ReadOnlyProperties(this, friendClassBadge);
    }


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


    /**
     * Creates an empty {@code ROPropertiesBuilder} (property list) with no default values.
     *
     * <BR /><BR />The initial capacity of a {@code Properties} object created
     * with this constructor is unspecified.
     */
    public ROPropertiesBuilder()
    { super(); }

    /**
     * Creates an empty {@code ROPropertiesBuilder} (property list) with no default values, and
     * with an initial size accommodating the specified number of elements without the need to
     * dynamically resize.
     *
     * @param initialCapacity the {@code Properties} will be sized to accommodate this many
     * elements
     * 
     * @throws IllegalArgumentException if the initial capacity is less than zero.
     */
    public ROPropertiesBuilder(int initialCapacity)
    { super(initialCapacity); }

    /**
     * Creates an empty {@code ROPropertiesBuilder} (property list) with the specified defaults.
     *
     * <BR /><BR />The initial capacity of a {@code Properties} object created with this
     * constructor is unspecified.
     *
     * @param defaults the defaults.
     */
    public ROPropertiesBuilder(Properties defaults)
    { super(defaults); }


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


    /**
     * Calls the {@code Hashtable} method {@code put}. Provided for parallelism with the
     * {@code getProperty} method.  Enforces use of {@code String's} for property keys and values.
     * The value returned is the result of the {@code Hashtable} call to {@code put}.
     *
     * @param key the key to be placed into this property list.
     * @param value the value corresponding to {@code key}.
     * 
     * @return the previous value of the specified key in this property list, or {@code null} if it
     * did not have one.
     * 
     * @see #getProperty
     */
    public synchronized Object setProperty(String key, String value)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.setProperty(key, value);
    }

    /**
     * Reads a property list (key and element pairs) from the input character stream in a simple
     * line-oriented format.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LOAD_DESC_READER>
     * 
     * @param reader the input character stream.
     * @throws IOException if an error occurred when reading from the input stream.
     * @throws IllegalArgumentException if a malformed Unicode escape appears in the input.
     * @throws NullPointerException if {@code reader} is null.
     */
    public synchronized void load(Reader reader) throws IOException
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        super.load(reader);
    }

    /**
     * Reads a property list (key and element pairs) from the input byte stream. The input stream
     * is in a simple line-oriented format as specified in
     * {@link #load(java.io.Reader) load(Reader)} and is assumed to use the ISO 8859-1 character
     * encoding; that is each byte is one Latin1 character. Characters not in Latin1, and certain
     * special characters, are represented in keys and elements using Unicode escapes as defined in
     * section {@code 3.3} of <cite>The Java Language Specification</cite>.
     * 
     * <BR /><BR />The specified stream remains open after this method returns.
     *
     * @param inStream the input stream.
     * @throws IOException if an error occurred when reading from the input stream.
     * 
     * @throws IllegalArgumentException if the input stream contains a malformed Unicode escape
     * sequence.
     * 
     * @throws NullPointerException if {@code inStream} is null.
     */
    public synchronized void load(InputStream inStream) throws IOException
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        super.load(inStream);
    }

    /**
     * Loads all of the properties represented by the XML document on the specified input stream
     * into this properties table.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LOADXML_DESC_INPUT_STRM>
     * 
     * @param in the input stream from which to read the XML document.
     * 
     * @throws IOException if reading from the specified input stream results in an
     * {@code IOException}.
     * 
     * @throws java.io.UnsupportedEncodingException if the document's encoding declaration can be
     * read and it specifies an encoding that is not supported
     * 
     * @throws InvalidPropertiesFormatException Data on input stream does not constitute a valid
     * XML document with the mandated document type.
     * 
     * @throws NullPointerException if {@code in} is null.
     *
     * @spec https://www.w3.org/TR/xml Extensible Markup Language (XML) 1.0 (Fifth Edition)
     * @see #storeToXML(OutputStream, String, String)
     * @see <a href="http://www.w3.org/TR/REC-xml/#charencoding">Character Encoding in Entities</a>
     */
    public synchronized void loadFromXML(InputStream in)
        throws IOException, InvalidPropertiesFormatException
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        super.loadFromXML(in);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Hashtable methods overridden and delegated to internal 'properties' instance
    // ********************************************************************************************
    // ********************************************************************************************


    @Override
    public synchronized Object put(Object key, Object value)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.put(key, value);
    }

    @Override
    public synchronized Object remove(Object key)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.remove(key);
    }

    @Override
    public synchronized void putAll(Map<?, ?> t)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        super.putAll(t);
    }

    @Override
    public synchronized void clear()
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        super.clear();
    }

    @Override
    public synchronized void replaceAll(BiFunction<Object, Object, ?> function)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        super.replaceAll(function);
    }

    @Override
    public synchronized Object putIfAbsent(Object key, Object value)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.putIfAbsent(key, value);
    }

    @Override
    public synchronized boolean remove(Object key, Object value)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.remove(key, value);
    }

    @Override
    public synchronized boolean replace(Object key, Object oldValue, Object newValue)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.replace(key, oldValue, newValue);
    }

    @Override
    public synchronized Object replace(Object key, Object value)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.replace(key, value);
    }

    @Override
    public synchronized Object computeIfAbsent
        (Object key, Function<Object, ?> mappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.computeIfAbsent(key, mappingFunction);
    }

    @Override
    public synchronized Object computeIfPresent
        (Object key, BiFunction<Object, Object, ?> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.computeIfPresent(key, remappingFunction);
    }

    @Override
    public synchronized Object compute
        (Object key, BiFunction<Object, Object, ?> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.compute(key, remappingFunction);
    }

    @Override
    public synchronized Object merge
        (Object key, Object value, BiFunction<Object, Object, ?> remappingFunction)
    {
        if (this.built) throw new AttemptedModificationException(ROP);
        return super.merge(key, value, remappingFunction);
    }


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


    // contains, containsKey, containsValue, elements, entrySet, forEach, get, getOrDefault,
    // getProperty, getProperty, hashCode, isEmpty, keys, keySet, list, list, propertyNames,
    // rehash, save, size, store, store, storeToXML, storeToXML, storeToXML, stringPropertyNames,
    // toString, values
    // 
    // Introspection Only:  contains, containsKey, containsValue, elements, forEach, get,
    //                      getOrDefault, getProperty, getProperty, hashCode, isEmpty, keys, list,
    //                      list, propertyNames, rehash, save, size, store, store, storeToXML,
    //                      storeToXML, storeToXML, stringPropertyNames, toString
    // 
    // Potential Mutator: entrySet, keySet, values

    /**
     * Restricts a back-door into the underlying data-structure.
     * <EMBED CLASS='external-html'DATA-RET_TYPE=Set DATA-FILE-ID=UNMODIFIABLE>
     * @return a {@code java.util.Set} that cannot modify this {@code Properties-Builder}
     */
    public Set<Map.Entry<Object, Object>> entrySet()
    { return Collections.unmodifiableSet(super.entrySet()); }

    Set<Map.Entry<Object, Object>> _entrySet(ReadOnlyProperties.AccessBadge friendClassBadge)
    { return super.entrySet(); }

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

    Set<Object> _keySet(ReadOnlyProperties.AccessBadge friendClassBadge)
    { return super.keySet(); }

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

    Collection<Object> _values(ReadOnlyProperties.AccessBadge friendClassBadge)
    { return super.values(); }


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


    /**
     * Compares the specified Object with this Builder for equality, as per the definition in the
     * private and internal field {@code 'properties'}.
     *
     * @param  o object to be compared for equality with this {@code ROPropertiesBuilder} 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 ROPropertiesBuilder)) return false;
        return super.equals((Properties) o);
    }

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

    private ROPropertiesBuilder(ROPropertiesBuilder rohtb)
    { super(rohtb); this.built=false; }
}