/*
 * 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.nio.charset.Charset;
import java.util.function.BiConsumer;
import java.util.function.BiFunction;

import Torello.Java.Additional.Ret2;
import Torello.Java.Additional.Tuple2;

import java.io.*;
import java.util.*;

/**
 * Immutable Wrapper for <CODE>java&#46;util&#46;Properties</CODE>, found in the "Java Collections
 * Framework".
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=Properties>
 * <EMBED CLASS='external-html' DATA-FILE-ID=DATA_CLASS>
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_MAIN")
public class ReadOnlyProperties extends ReadOnlyHashtable<Object, Object>
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Protected & Private Fields, Methods, Statics
    // ********************************************************************************************
    // ********************************************************************************************


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

    // Minor Optimization where new Properties's that have no contents always re-use this static
    // instance.

    private static final Properties EMPTY_PROPERTIES = new Properties(0);

    // Singleton & Empty ReadOnlyProperties, Uses the "Supplier Constructor"
    private static final ReadOnlyProperties EMPTY_READONLY_PROPERTIES =
        new ReadOnlyProperties(EMPTY_PROPERTIES);

    // The actual Properties used by this instance.
    private final Properties properties;

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

    private final boolean fromBuilderOrProperties;

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


    // ********************************************************************************************
    // ********************************************************************************************
    // Builder, Acess-Badge Constructor - and Static "Empty" getter (which is used by the builder)
    // ********************************************************************************************
    // ********************************************************************************************


    public static ReadOnlyProperties emptyROP()
    { return EMPTY_READONLY_PROPERTIES; }

    // 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
    // ROPropertiesBuilder
    //
    // This is the Constructor used by the Builder.  It has a "Zero-Size" Optimization

    ReadOnlyProperties(ROPropertiesBuilder ropb, ROPropertiesBuilder.AccessBadge badge)
    {
        // This is a little bizarre, but necessary.  Properties extends Hashtable
        super(friendClassBadge);

        Objects.requireNonNull(badge, "Access Badge is null.  Requires Friend-Class Badge");

        this.fromBuilderOrProperties = true;
        this.properties = ropb;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Clones parameter {@code 'properties'} (and saves it) in order to guarantee that
     * {@code 'this'} instance is Read-Only and furthermore shielded from outside modification.
     * 
     * @param properties The {@code Properties} to be cloned and saved into this instance internal
     * and private {@code 'properties'} field.
     */
    @SuppressWarnings("unchecked")
    public ReadOnlyProperties(Properties properties)
    {
        // This is a little bizarre, but necessary.  Properties extends Hashtable
        super(friendClassBadge);
        this.fromBuilderOrProperties = false;

        // TO-DO: FIX-ME, CLONE IS NOT ACCEPTABLE IN READ-ONLY !!!  IT IS A BACK-DOOR !!!
        this.properties = (Properties) properties.clone();
    }

    /**
     * If only a small amount of processing needs to be done on the contents of some Java
     * Map, and using an entire Builder-Class seems disproportionately complex - <I>this
     * constructor can convert any Java {@code Map} into a {@code ReadOnlyProperties}, using
     * a simple {@code 'mapTranslator'}</I>.
     * 
     * @param <A> The Key-Type of the User-Provided {@code Map}.
     * @param <B> The Value-Type of the User-Provided {@code Map}.
     * 
     * @param map Any Java {@code Map}.
     * 
     * @param mapTranslator A function for mapping the iterated elements of Map-Types {@code 'A'}
     * and {@code 'B'}, into the actual {@code Properties's} Key and Value Type {@code 'String'}.
     * 
     * <BR /><BR />If this parameter is passed null, this method will throw a
     * {@code NullPointerException}.
     * 
     * @throws NullPointerException if either parameter {@code 'i'} or parameter 
     * {@code 'mapTranslator'} is passed null.
     */
    public <A, B> ReadOnlyProperties
        (Map<A, B> map, BiFunction<A, B, Ret2<String, String>> mapTranslator)
    {
        super(friendClassBadge);

        Objects.requireNonNull(mapTranslator, "You have passed null to parameter 'mapTranslator'");

        fromBuilderOrProperties = false;

        Properties properties = new Properties(map.size());

        for (Map.Entry<A, B> entry : map.entrySet())
        {
            Ret2<String, String> ret2 = mapTranslator.apply(entry.getKey(), entry.getValue());
            properties.put(ret2.a, ret2.b);
        }

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.properties = (properties.size() == 0) ? EMPTY_PROPERTIES : properties;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // More Constructors, March 2024
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * 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 {@code 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.
     *
     * <BR /><BR /><SPAN CLASS=CopiedJDK>This Detail-Comment was copied from class:
     * {@code java.util.Properties}, <B>JDK 21</B>
     * 
     * <BR /><BR /><B>Method:</B> Properties.load(InputStream.inStream)
     * </SPAN>
     * 
     * @param inStream the input stream.
     * @param sizeIfKnown <EMBED CLASS='external-html' DATA-FILE-ID=PROP_ICAPACITY>
     * @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 ReadOnlyProperties(InputStream inStream, Integer sizeIfKnown) throws IOException
    {
        super(friendClassBadge);

        this.fromBuilderOrProperties = false;

        this.properties = (sizeIfKnown != null) ? new Properties(sizeIfKnown) : new Properties();

        this.properties.load(inStream);
    }

    /**
     * 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>
     * 
     * <BR /><BR /><SPAN CLASS=CopiedJDK>This Detail-Comment was copied from class:
     * {@code java.util.Properties}, <B>JDK 21</B>
     * 
     * <BR /><BR /><B>Method:</B> Properties.load(InputStream.inStream)
     * </SPAN>
     * 
     * @param reader        the input character stream.
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=PROP_ICAPACITY>
     * @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 ReadOnlyProperties(Reader reader, Integer sizeIfKnown) throws IOException 
    {
        super(friendClassBadge);

        this.fromBuilderOrProperties = false;

        this.properties = (sizeIfKnown != null) ? new Properties(sizeIfKnown) : new Properties();

        this.properties.load(reader);
    }

    /**
     * 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>
     * 
     * <BR /><BR /><SPAN CLASS=CopiedJDK>This Detail-Comment was copied from class:
     * {@code java.util.Properties}, <B>JDK 21</B>
     * 
     * <BR /><BR /><B>Method:</B> Properties.load(InputStream.inStream)
     * </SPAN>
     * 
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=PROP_ICAPACITY>
     * @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 ReadOnlyProperties(Integer sizeIfKnown, InputStream in)
        throws IOException, UnsupportedEncodingException, InvalidPropertiesFormatException
    {
        super(friendClassBadge);

        this.fromBuilderOrProperties = false;

        this.properties = (sizeIfKnown != null) ? new Properties(sizeIfKnown) : new Properties();

        this.properties.loadFromXML(in);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // One More Constructor, for good luck - March 2024
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Builds a {@code Properties} instance using the {@code 'refHolder'} &amp;
     * {@code 'computeNextEntry'} combination.
     * 
     * @param refHolder         <EMBED CLASS='external-html' DATA-FILE-ID=REF_HOLDER>
     * @param computeNextEntry  <EMBED CLASS='external-html' DATA-FILE-ID=COMPUTE_NEXT_RUN>
     * @param sizeIfKnown       <EMBED CLASS='external-html' DATA-FILE-ID=PROP_ICAPACITY>
     */
    public ReadOnlyProperties(
            Tuple2<Object, Object>  refHolder,
            Runnable                computeNextEntry,
            Integer                 sizeIfKnown
        )
    {
        super(friendClassBadge);

        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

        fromBuilderOrProperties = false;

        Properties properties = new Properties(((sizeIfKnown == null)  ? 16 : sizeIfKnown));

        do
        {
            computeNextEntry.run();
            if ((refHolder.a == null) && (refHolder.b == null)) break;
            properties.put(refHolder.a, refHolder.b);
        }
        while (true);

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.properties = (properties.size() == 0) ? EMPTY_PROPERTIES : properties;
    }


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


    /**
     * Clone's {@code 'this'} instance internal {@code Properties<E>} field, and returns it. 
     * <EMBED CLASS='external-html' DATA-TYPE=Properties DATA-FILE-ID=CLONE_TO>
     * 
     * @return An independent, mutable copy of {@code 'this'} instance' internal
     * {@code Properties<E>} data-structure.
     */
    @SuppressWarnings("unchecked") // The clone() cast
    public Properties cloneToProperties()
    {
        return fromBuilderOrProperties
            ? new Properties(this.properties)
            : (Properties) this.properties.clone();
    }

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


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


    /**
     * Writes this property list (key and element pairs) from this instance' internal
     * {@code Properties} table to the output character stream (in a format suitable for using the
     * {@code Properties.load(Reader)} method.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=STORE_DESC_WRITER>
     * 
     * @param writer an output character stream writer.
     * @param comments a description of the property list.
     * 
     * @throws IOException if writing this property list to the specified output stream throws an
     * {@code IOException}.
     * 
     * @throws ClassCastException  if this {@code Properties} object contains any keys or values
     * that are not {@code Strings}.
     * 
     * @throws NullPointerException  if {@code writer} is null.
     */
    public void store(Writer writer, String comments)
        throws IOException
    { this.properties.store(writer, comments); }

    /**
     * Writes this property list (key and element pairs) from this instance' internal
     * {@code Properties} table to the output character stream in a format suitable for using the
     * {@code Properties.load(InputStream)} method.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=STORE_DESC_OUTPUTS>
     * 
     * @param out an output stream.
     * @param comments a description of the property list.
     * 
     * @throws IOException if writing this property list to the specified output stream throws an
     * {@code IOException}.
     * 
     * @throws ClassCastException if this {@code Properties} object contains any keys or values
     * that are not {@code Strings}.
     * 
     * @throws NullPointerException if {@code out} is null.
     */
    public void store(OutputStream out, String comments)
        throws IOException
    { this.properties.store(out, comments); }

    /**
     * Emits an XML document representing all of the properties contained in this table.
     *
     * <BR /><BR /> An invocation of this method of the form {@code props.storeToXML(os, comment)}
     * behaves in exactly the same way as the invocation
     * {@code props.storeToXML(os, comment, "UTF-8");}.
     *
     * @param os the output stream on which to emit the XML document.
     * @param comment a description of the property list, or {@code null} if no comment is desired.
     * 
     * @throws IOException if writing to the specified output stream results in an
     * {@code IOException}.
     * 
     * @throws NullPointerException if {@code os} is null.
     * 
     * @throws ClassCastException  if this {@code Properties} object contains any keys or values
     * that are not {@code Strings}.
     */
    public void storeToXML(OutputStream os, String comment)
        throws IOException
    { this.properties.storeToXML(os, comment); }

    /**
     * Emits an XML document representing all of the properties contained in this table, using the
     * specified encoding.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=STOREXML_DESC_OS_S_S>
     * 
     * @param os the output stream on which to emit the XML document.
     * @param comment a description of the property list, or {@code null} if no comment is desired.
     * 
     * @param  encoding the name of a supported
     * <a href="../lang/package-summary.html#charenc">character encoding</a>
     *
     * @throws IOException if writing to the specified output stream results in an
     * {@code IOException}.
     * 
     * @throws java.io.UnsupportedEncodingException if the encoding is not supported by the
     * implementation.
     * 
     * @throws NullPointerException if {@code os} is {@code null}, or if {@code encoding} is
     * {@code null}.
     * 
     * @throws ClassCastException  if this {@code Properties} object contains any keys or values
     * that are not {@code Strings}.
     *
     * @spec https://www.w3.org/TR/xml Extensible Markup Language (XML) 1.0 (Fifth Edition)
     * @see <a href="http://www.w3.org/TR/REC-xml/#charencoding">Character Encoding in Entities</a>
     */
    public void storeToXML(OutputStream os, String comment, String encoding) throws IOException
    { this.properties.storeToXML(os, comment, encoding); }

    /**
     * Emits an XML document representing all of the properties contained in this table, using
     * the specified encoding.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=STOREXML_DESC_OS_S_CHRS>
     * 
     * @param os the output stream on which to emit the XML document.
     * @param comment a description of the property list, or {@code null} if no comment is desired.
     * @param charset the charset
     *
     * @throws IOException if writing to the specified output stream results in an
     * {@code IOException}.
     * 
     * @throws NullPointerException if {@code os} or {@code charset} is {@code null}.
     * 
     * @throws ClassCastException  if this {@code Properties} object contains any keys or values
     * that are not {@code Strings}.
     *
     * @spec https://www.w3.org/TR/xml Extensible Markup Language (XML) 1.0 (Fifth Edition)
     * @see <a href="http://www.w3.org/TR/REC-xml/#charencoding">Character Encoding in Entities</a>
     */
    public void storeToXML(OutputStream os, String comment, Charset charset) throws IOException
    { this.properties.storeToXML(os, comment, charset); }

    /**
     * Searches for the property with the specified key in this property list.  If the key is not
     * found in this property list, the default property list, and its defaults, recursively, are
     * then checked. The method returns {@code null} if the property is not found.
     *
     * @param key the property key.
     * @return the value in this property list with the specified key value.
     */
    public String getProperty(String key)
    { return this.properties.getProperty(key); }

    /**
     * Searches for the property with the specified key in this property list.  If the key is not
     * found in this property list, the default property list, and its defaults, recursively, are
     * then checked. The method returns the default value argument if the property is not found.
     *
     * @param key the hashtable key.
     * @param defaultValue a default value.
     *
     * @return the value in this property list with the specified key value.
     */
    public String getProperty(String key, String defaultValue)
    { return this.properties.getProperty(key, defaultValue); }

    /**
     * Returns an enumeration of all the keys in this property list, including distinct keys in
     * the default property list if a key of the same name has not already been found from the main
     * properties list.
     *
     * @return an enumeration of all the keys in this property list, including the keys in the
     * default property list.
     * 
     * @throws ClassCastException if any key in this property list is not a {@code String}.
     * @see #stringPropertyNames
     */
    public Enumeration<?> propertyNames()
    { return this.properties.propertyNames(); }

    /**
     * Returns an unmodifiable set of keys from this property list where the key and its
     * corresponding value are strings, including distinct keys in the default property list if a
     * key of the same name has not already been found from the main properties list.  Properties
     * whose key or value is not of type {@code String} are omitted.
     * 
     * <BR /><BR />The returned set is not backed by this {@code Properties} object.  Changes to
     * this {@code Properties} object are not reflected in the returned set.
     *
     * @return  an unmodifiable set of keys in this property list where the key and its
     * corresponding value are strings, including the keys in the default property list.
     */
    public ReadOnlySet<String> stringPropertyNames()
    { return InterfaceBuilder.toReadOnlySet(this.properties.stringPropertyNames()); }

    /**
     * Prints this property list out to the specified output stream.  This method is useful for
     * debugging.
     *
     * @param out an output stream.
     * @throws ClassCastException if any key in this property list is not a {@code String}.
     */
    public void list(PrintStream out)
    { this.properties.list(out); }

    /**
     * Prints this property list out to the specified output stream.  This method is useful for
     * debugging.
     *
     * @param out an output stream.
     * @throws ClassCastException if any key in this property list is not a {@code String}.
     */
    public void list(PrintWriter out)
    { this.properties.list(out); }

    //
    // Hashtable methods overridden and delegated to a ConcurrentHashMap instance

    @Override
    public int size()
    { return this.properties.size(); }

    @Override
    public boolean isEmpty()
    { return this.properties.isEmpty(); }

    @Override
    public Enumeration<Object> keys()
    { return this.properties.keys(); }

    @Override
    public Enumeration<Object> elements()
    { return this.properties.elements(); }

    @Override
    public boolean contains(Object value)
    { return this.properties.contains(value); }

    @Override
    public boolean containsValue(Object value)
    { return this.properties.containsValue(value); }

    @Override
    public boolean containsKey(Object key)
    { return this.properties.containsKey(key); }

    @Override
    public Object get(Object key)
    { return this.properties.get(key); }

    @Override
    public ReadOnlySet<Object> keySet()
    {
        return InterfaceBuilder.toReadOnlySet(
            fromBuilderOrProperties
                ? ((ROPropertiesBuilder) this.properties)._keySet(friendClassBadge)
                : this.properties.keySet()
        );
    }

    @Override
    public ReadOnlyCollection<Object> values()
    {
        return InterfaceBuilder.toReadOnlyCollection(
            fromBuilderOrProperties
                ? ((ROPropertiesBuilder) this.properties)._values(friendClassBadge)
                : this.properties.values()
        );
    }

    @Override
    public ReadOnlySet<ReadOnlyMap.Entry<Object, Object>> entrySet()
    {
        return ROHelpers.toReadOnlyEntrySet(
            fromBuilderOrProperties
                ? ((ROPropertiesBuilder) this.properties)._entrySet(friendClassBadge)
                : this.properties.entrySet()
        );
    }

    @Override
    public Object getOrDefault(Object key, Object defaultValue)
    { return this.properties.getOrDefault(key, defaultValue); }

    @Override
    public synchronized void forEach(BiConsumer<? super Object, ? super Object> action)
    { this.properties.forEach(action); }


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


    /**
     * Returns a {@code String} representation of this {@code Properties}. 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 Properties}
     */
    @Override
    public String toString()
    { return this.properties.toString(); }

    /**
     * Compares the specified Object with this List for equality, as per the definition in the 
     * class {@code java.util.Properties}.
     *
     * @param  o object to be compared for equality with this {@code Properties}
     * @return {@code TRUE} if the specified Object is equal to this map
     */
    @Override
    public boolean equals(Object o)
    {
        if (this == o) return true;
        if (! (o instanceof ReadOnlyProperties)) return false;
        return this.properties.equals(((ReadOnlyProperties) o).properties);
    }

    @Override
    public synchronized int hashCode()
    { return this.properties.hashCode(); }
}