/*

 * Copyright (c) 1995, 2019, 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 java.util;

import java.io.IOException;

import java.io.PrintStream;

import java.io.PrintWriter;

import java.io.InputStream;

import java.io.OutputStream;

import java.io.Reader;

import java.io.Writer;

import java.io.OutputStreamWriter;

import java.io.BufferedWriter;

import java.io.ObjectInputStream;

import java.io.ObjectOutputStream;

import java.io.StreamCorruptedException;

import java.io.UnsupportedEncodingException;

import java.nio.charset.Charset;

import java.nio.charset.IllegalCharsetNameException;

import java.nio.charset.UnsupportedCharsetException;

import java.util.concurrent.ConcurrentHashMap;

import java.util.function.BiConsumer;

import java.util.function.BiFunction;

import java.util.function.Function;

import jdk.internal.access.SharedSecrets;

import jdk.internal.misc.Unsafe;

import jdk.internal.util.ArraysSupport;

import jdk.internal.util.xml.PropertiesDefaultHandler;

/**

 * The {@code Properties} class represents a persistent set of

 * properties. The {@code Properties} can be saved to a stream

 * or loaded from a stream. Each key and its corresponding value in

 * the property list is a string.

 * <p>

 * A property list can contain another property list as its

 * "defaults"; this second property list is searched if

 * the property key is not found in the original property list.

 * <p>

 * Because {@code Properties} inherits from {@code Hashtable}, the

 * {@code put} and {@code putAll} methods can be applied to a

 * {@code Properties} object.  Their use is strongly discouraged as they

 * allow the caller to insert entries whose keys or values are not

 * {@code Strings}.  The {@code setProperty} method should be used

 * instead.  If the {@code store} or {@code save} method is called

 * on a "compromised" {@code Properties} object that contains a

 * non-{@code String} key or value, the call will fail. Similarly,

 * the call to the {@code propertyNames} or {@code list} method

 * will fail if it is called on a "compromised" {@code Properties}

 * object that contains a non-{@code String} key.

 *

 * <p>

 * The iterators returned by the {@code iterator} method of this class's

 * "collection views" (that is, {@code entrySet()}, {@code keySet()}, and

 * {@code values()}) may not fail-fast (unlike the Hashtable implementation).

 * These iterators are guaranteed to traverse elements as they existed upon

 * construction exactly once, and may (but are not guaranteed to) reflect any

 * modifications subsequent to construction.

 * <p>

 * The {@link #load(java.io.Reader) load(Reader)} {@code /}

 * {@link #store(java.io.Writer, java.lang.String) store(Writer, String)}

 * methods load and store properties from and to a character based stream

 * in a simple line-oriented format specified below.

 *

 * The {@link #load(java.io.InputStream) load(InputStream)} {@code /}

 * {@link #store(java.io.OutputStream, java.lang.String) store(OutputStream, String)}

 * methods work the same way as the load(Reader)/store(Writer, String) pair, except

 * the input/output stream is encoded in ISO 8859-1 character encoding.

 * Characters that cannot be directly represented in this encoding can be written using

 * Unicode escapes as defined in section 3.3 of

 * <cite>The Java&trade; Language Specification</cite>;

 * only a single 'u' character is allowed in an escape

 * sequence.

 *

 * <p> The {@link #loadFromXML(InputStream)} and {@link

 * #storeToXML(OutputStream, String, String)} methods load and store properties

 * in a simple XML format.  By default the UTF-8 character encoding is used,

 * however a specific encoding may be specified if required. Implementations

 * are required to support UTF-8 and UTF-16 and may support other encodings.

 * An XML properties document has the following DOCTYPE declaration:

 *

 * <pre>

 * <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">

 * </pre>

 * Note that the system URI (http://java.sun.com/dtd/properties.dtd) is

 * <i>not</i> accessed when exporting or importing properties; it merely

 * serves as a string to uniquely identify the DTD, which is:

 * <pre>

 *    <?xml version="1.0" encoding="UTF-8"?>

 *

 *    <!-- DTD for properties -->

 *

 *    <!ELEMENT properties ( comment?, entry* ) >

 *

 *    <!ATTLIST properties version CDATA #FIXED "1.0">

 *

 *    <!ELEMENT comment (#PCDATA) >

 *

 *    <!ELEMENT entry (#PCDATA) >

 *

 *    <!ATTLIST entry key CDATA #REQUIRED>

 * </pre>

 *

 * <p>This class is thread-safe: multiple threads can share a single

 * {@code Properties} object without the need for external synchronization.

 *

 * @apiNote

 * The {@code Properties} class does not inherit the concept of a load factor

 * from its superclass, {@code Hashtable}.

 *

 * @author  Arthur van Hoff

 * @author  Michael McCloskey

 * @author  Xueming Shen

 * @since   1.0

 */

public

class Properties extends Hashtable<Object,Object> {

    /**

     * use serialVersionUID from JDK 1.1.X for interoperability

     */

    @java.io.Serial

    private static final long serialVersionUID = 4112578634029874840L;

    private static final Unsafe UNSAFE = Unsafe.getUnsafe();

    /**

     * A property list that contains default values for any keys not

     * found in this property list.

     *

     * @serial

     */

    protected volatile Properties defaults;

    /**

     * Properties does not store values in its inherited Hashtable, but instead

     * in an internal ConcurrentHashMap.  Synchronization is omitted from

     * simple read operations.  Writes and bulk operations remain synchronized,

     * as in Hashtable.

     */

    private transient volatile ConcurrentHashMap<Object, Object> map;

    /**

     * Creates an empty property list with no default values.

     *

     * @implNote The initial capacity of a {@code Properties} object created

     * with this constructor is unspecified.

     */

    public Properties() {

        this(null, 8);

    }

    /**

     * Creates an empty 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 Properties(int initialCapacity) {

        this(null, initialCapacity);

    }

    /**

     * Creates an empty property list with the specified defaults.

     *

     * @implNote The initial capacity of a {@code Properties} object created

     * with this constructor is unspecified.

     *

     * @param   defaults   the defaults.

     */

    public Properties(Properties defaults) {

        this(defaults, 8);

    }

    private Properties(Properties defaults, int initialCapacity) {

        // use package-private constructor to

        // initialize unused fields with dummy values

        super((Void) null);

        map = new ConcurrentHashMap<>(initialCapacity);

        this.defaults = defaults;

        // Ensure writes can't be reordered

        UNSAFE.storeFence();

    }

    /**

     * Calls the {@code Hashtable} method {@code put}. Provided for

     * parallelism with the {@code getProperty} method. Enforces use of

     * strings 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

     * @since    1.2

     */

    public synchronized Object setProperty(String key, String value) {

        return put(key, value);

    }

    /**

     * Reads a property list (key and element pairs) from the input

     * character stream in a simple line-oriented format.

     * <p>

     * Properties are processed in terms of lines. There are two

     * kinds of line, <i>natural lines</i> and <i>logical lines</i>.

     * A natural line is defined as a line of

     * characters that is terminated either by a set of line terminator

     * characters ({@code \n} or {@code \r} or {@code \r\n})

     * or by the end of the stream. A natural line may be either a blank line,

     * a comment line, or hold all or some of a key-element pair. A logical

     * line holds all the data of a key-element pair, which may be spread

     * out across several adjacent natural lines by escaping

     * the line terminator sequence with a backslash character

     * {@code \}.  Note that a comment line cannot be extended

     * in this manner; every natural line that is a comment must have

     * its own comment indicator, as described below. Lines are read from

     * input until the end of the stream is reached.

     *

     * <p>

     * A natural line that contains only white space characters is

     * considered blank and is ignored.  A comment line has an ASCII

     * {@code '#'} or {@code '!'} as its first non-white

     * space character; comment lines are also ignored and do not

     * encode key-element information.  In addition to line

     * terminators, this format considers the characters space

     * ({@code ' '}, {@code '\u005Cu0020'}), tab

     * ({@code '\t'}, {@code '\u005Cu0009'}), and form feed

     * ({@code '\f'}, {@code '\u005Cu000C'}) to be white

     * space.

     *

     * <p>

     * If a logical line is spread across several natural lines, the

     * backslash escaping the line terminator sequence, the line

     * terminator sequence, and any white space at the start of the

     * following line have no affect on the key or element values.

     * The remainder of the discussion of key and element parsing

     * (when loading) will assume all the characters constituting

     * the key and element appear on a single natural line after

     * line continuation characters have been removed.  Note that

     * it is <i>not</i> sufficient to only examine the character

     * preceding a line terminator sequence to decide if the line

     * terminator is escaped; there must be an odd number of

     * contiguous backslashes for the line terminator to be escaped.

     * Since the input is processed from left to right, a

     * non-zero even number of 2<i>n</i> contiguous backslashes

     * before a line terminator (or elsewhere) encodes <i>n</i>

     * backslashes after escape processing.

     *

     * <p>

     * The key contains all of the characters in the line starting

     * with the first non-white space character and up to, but not

     * including, the first unescaped {@code '='},

     * {@code ':'}, or white space character other than a line

     * terminator. All of these key termination characters may be

     * included in the key by escaping them with a preceding backslash

     * character; for example,<p>

     *

     * {@code \:\=}<p>

     *

     * would be the two-character key {@code ":="}.  Line

     * terminator characters can be included using {@code \r} and

     * {@code \n} escape sequences.  Any white space after the

     * key is skipped; if the first non-white space character after

     * the key is {@code '='} or {@code ':'}, then it is

     * ignored and any white space characters after it are also

     * skipped.  All remaining characters on the line become part of

     * the associated element string; if there are no remaining

     * characters, the element is the empty string

     * {@code ""}.  Once the raw character sequences

     * constituting the key and element are identified, escape

     * processing is performed as described above.

     *

     * <p>

     * As an example, each of the following three lines specifies the key

     * {@code "Truth"} and the associated element value

     * {@code "Beauty"}:

     * <pre>

     * Truth = Beauty

     *  Truth:Beauty

     * Truth                    :Beauty

     * </pre>

     * As another example, the following three lines specify a single

     * property:

     * <pre>

     * fruits                           apple, banana, pear, \

     *                                  cantaloupe, watermelon, \

     *                                  kiwi, mango

     * </pre>

     * The key is {@code "fruits"} and the associated element is:

     * <pre>"apple, banana, pear, cantaloupe, watermelon, kiwi, mango"</pre>

     * Note that a space appears before each {@code \} so that a space

     * will appear after each comma in the final result; the {@code \},

     * line terminator, and leading white space on the continuation line are

     * merely discarded and are <i>not</i> replaced by one or more other

     * characters.

     * <p>

     * As a third example, the line:

     * <pre>cheeses

     * </pre>

     * specifies that the key is {@code "cheeses"} and the associated

     * element is the empty string {@code ""}.

     * <p>

     * <a id="unicodeescapes"></a>

     * Characters in keys and elements can be represented in escape

     * sequences similar to those used for character and string literals

     * (see sections 3.3 and 3.10.6 of

     * <cite>The Java&trade; Language Specification</cite>).

     *

     * The differences from the character escape sequences and Unicode

     * escapes used for characters and strings are:

     *

     * <ul>

     * <li> Octal escapes are not recognized.

     *

     * <li> The character sequence {@code \b} does <i>not</i>

     * represent a backspace character.

     *

     * <li> The method does not treat a backslash character,

     * {@code \}, before a non-valid escape character as an

     * error; the backslash is silently dropped.  For example, in a

     * Java string the sequence {@code "\z"} would cause a

     * compile time error.  In contrast, this method silently drops

     * the backslash.  Therefore, this method treats the two character

     * sequence {@code "\b"} as equivalent to the single

     * character {@code 'b'}.

     *

     * <li> Escapes are not necessary for single and double quotes;

     * however, by the rule above, single and double quote characters

     * preceded by a backslash still yield single and double quote

     * characters, respectively.

     *

     * <li> Only a single 'u' character is allowed in a Unicode escape

     * sequence.

     *

     * </ul>

     * <p>

     * The specified stream remains open after this method returns.

     *

     * @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.

     * @since   1.6

     */

    public synchronized void load(Reader reader) throws IOException {

        Objects.requireNonNull(reader, "reader parameter is null");

        load0(new LineReader(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 3.3 of

     * <cite>The Java&trade; Language Specification</cite>.

     * <p>

     * 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.

     * @since 1.2

     */

    public synchronized void load(InputStream inStream) throws IOException {

        Objects.requireNonNull(inStream, "inStream parameter is null");

        load0(new LineReader(inStream));

    }

    private void load0(LineReader lr) throws IOException {

        StringBuilder outBuffer = new StringBuilder();

        int limit;

        int keyLen;

        int valueStart;

        boolean hasSep;

        boolean precedingBackslash;

        while ((limit = lr.readLine()) >= 0) {

            keyLen = 0;

            valueStart = limit;

            hasSep = false;

            //System.out.println("line=<" + new String(lineBuf, 0, limit) + ">");

            precedingBackslash = false;

            while (keyLen < limit) {

                char c = lr.lineBuf[keyLen];

                //need check if escaped.

                if ((c == '=' ||  c == ':') && !precedingBackslash) {

                    valueStart = keyLen + 1;

                    hasSep = true;

                    break;

                } else if ((c == ' ' || c == '\t' ||  c == '\f') && !precedingBackslash) {

                    valueStart = keyLen + 1;

                    break;

                }

                if (c == '\\') {

                    precedingBackslash = !precedingBackslash;

                } else {

                    precedingBackslash = false;

                }

                keyLen++;

            }

            while (valueStart < limit) {

                char c = lr.lineBuf[valueStart];

                if (c != ' ' && c != '\t' &&  c != '\f') {

                    if (!hasSep && (c == '=' ||  c == ':')) {

                        hasSep = true;

                    } else {

                        break;

                    }

                }

                valueStart++;

            }

            String key = loadConvert(lr.lineBuf, 0, keyLen, outBuffer);

            String value = loadConvert(lr.lineBuf, valueStart, limit - valueStart, outBuffer);

            put(key, value);

        }

    }

    /* Read in a "logical line" from an InputStream/Reader, skip all comment

     * and blank lines and filter out those leading whitespace characters

     * (\u0020, \u0009 and \u000c) from the beginning of a "natural line".

     * Method returns the char length of the "logical line" and stores

     * the line in "lineBuf".

     */

    private static class LineReader {

        LineReader(InputStream inStream) {

            this.inStream = inStream;

            inByteBuf = new byte[8192];

        }

        LineReader(Reader reader) {

            this.reader = reader;

            inCharBuf = new char[8192];

        }

        char[] lineBuf = new char[1024];

        private byte[] inByteBuf;

        private char[] inCharBuf;

        private int inLimit = 0;

        private int inOff = 0;

        private InputStream inStream;

        private Reader reader;

        int readLine() throws IOException {

            // use locals to optimize for interpreted performance

            int len = 0;

            int off = inOff;

            int limit = inLimit;

            boolean skipWhiteSpace = true;

            boolean appendedLineBegin = false;

            boolean precedingBackslash = false;

            boolean fromStream = inStream != null;

            byte[] byteBuf = inByteBuf;

            char[] charBuf = inCharBuf;

            char[] lineBuf = this.lineBuf;

            char c;

            while (true) {

                if (off >= limit) {

                    inLimit = limit = fromStream ? inStream.read(byteBuf)

                                                 : reader.read(charBuf);

                    if (limit <= 0) {

                        if (len == 0) {

                            return -1;

                        }

                        return precedingBackslash ? len - 1 : len;