Class ReadOnlyProperties

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, ReadOnlyDictionary<java.lang.Object,​java.lang.Object>, ReadOnlyMap<java.lang.Object,​java.lang.Object>
    public class ReadOnlyProperties
extends ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
    This class was originally copied from GitHub's Open-JDK Account. It has been heavily modified as all method bodies have been removed; although few changes were applied to the file's Javadoc Commenting. Method and parameter names & types have not been modified whatsoever - although several methods have been eliminated.

    This file contains quite a bit of Wrapper-Code which has been placed around the code from the original Open JDK-21 Source-File of the same (or, rather, highly similar) Class-Name. The original JDK Source-File may be viewed on the JDK-21 GitHub public (and, coincidentally, Read-Only) Source-Release archive for Java Package java.util.*

    The Original '.java' Source-File's Header-Copyright Information is included here: File Copyright. Within that Copyright Notice, it is suggested that a copy of the GNU Public License V2 also be included alongside.
    Immutable Wrapper for java.util.Properties, found in the "Java Collections Framework".

    Immutable Wrapper Class:
    This data class contains all of the methods that the standard Java class 'Properties' contains - except those which would directly or indirectly modify / mutate the internal data-structure.

    In order to guarantee that the contents and values of this Properties remain constant and unchanged, this class retains an internal Properties, and assigns it the Java modifier 'private' to prevent any outside, unwanted modification. This class' own methods are all trivial, single-line wrappers that invoke the original java.util methods, but leave out any & all wrappers for methods that have the ability to modify, update, remove or insert values into the internal and private Properties.

    Finally, this class offers a Read Only Guarantee, which is enforced by preventing any instantiation of this class from occuring that would allow outside references of its internal, private Properties field

    Immutable interface Inheritance-Tree:
    This class implements a variant of the JDK's java.util.* Interface-Stack, all of which have been slightly modified (and renamed to add the prefix 'ReadOnly' to their names). This decision was necessary because many of the support functions inside Java Collection Framework classes have utility / helper methods that retrieve & generate Sub-Maps and Sub-Sets that are linked to the original Collection's, Set's and Map's from whence they were produced.

    These Sub-Map / Sub-Set retrieval methods all sing the same refrain - changes to the returned Map / Set will be reflected into 'this' instance, and vice-versa.

    These Sub-Map's and Sub-Set's would easily (even though 'accidentally') provide a dangerous back-door means for modifying and updating a Collection that is claiming to be Read-Only & Immutable.

    As a result, the decision was made to also port all of the java.util.* interfaces, such as Set, Map, List & Collection, into the Read-Only Collections Framework by renaming them to ReadOnlySet, ReadOnlyMap, & ReadOnlyCollection - and of course to remove / eliminate all Mutator-Methods from those interfaces. This extra step further guarantees the provision that this Data-Class is, truly, Read-Only and un-modifiable.

    Self-Referential ReadOnlyProperties's
    Though likely uncommon in most typical software projects, it is possible for a Properties to actually contain a reference to itself. However, in the translation from a standard Properties to a ReadOnlyProperties, there is actually no direct and realizable way to preserve any self-referential pointers inside the ReadOnlyProperties which is being constructed.

    Java's Generic Type-System, generally, makes such references nearly (but not completely) impossible. Unless you have assigned java.lang.Object to the Data-Class' Generic-Type, there is likely no common Ancestor-Type that would inherit both a ReadOnlyProperties, and the other objects in your data-set.

    As a result, if you happen to pass an instance of data that contains references or pointers to itself, those pointers will not be updated to reference the Read-Only variant of your Data-Structure when that Data-Structure is created. The ReadOnlyProperties that you get back will simply contain pointers to the original Data-Structure you passed to the constructor of this class!
    See Also:
    Serialized Form


    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final long serialVersionUID = 1;

    • Constructor Detail

      • ReadOnlyProperties

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyProperties​(java.util.Properties properties)
        Clones parameter 'properties' (and saves it) in order to guarantee that 'this' instance is Read-Only and furthermore shielded from outside modification.
        Parameters:
        properties - The Properties to be cloned and saved into this instance internal and private 'properties' field.
        Code:
        Exact Constructor Body:
         // 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();

      • ReadOnlyProperties

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyProperties​
            (java.util.Map<A,​B> map,
             java.util.function.BiFunction<A,​B,​Ret2<java.lang.String,​java.lang.String>> mapTranslator)
        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 - this constructor can convert any Java Map into a ReadOnlyProperties, using a simple 'mapTranslator'.
        Type Parameters:
        A - The Key-Type of the User-Provided Map.
        B - The Value-Type of the User-Provided Map.
        Parameters:
        map - Any Java Map.
        mapTranslator - A function for mapping the iterated elements of Map-Types 'A' and 'B', into the actual Properties's Key and Value Type 'String'.

        If this parameter is passed null, this method will throw a NullPointerException.
        Throws:
        java.lang.NullPointerException - if either parameter 'i' or parameter 'mapTranslator' is passed null.
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyProperties

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyProperties​(java.io.InputStream inStream,
                          java.lang.Integer sizeIfKnown)
                   throws java.io.IOException
        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 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 The Java Language Specification.

        The specified stream remains open after this method returns.

        This Detail-Comment was copied from class: java.util.Properties, JDK 21

        Method: Properties.load(InputStream.inStream)
        Parameters:
        inStream - the input stream.
        sizeIfKnown - If the number of elements to be inserted is known, this value / size may be provided, here, to parameter 'sizeIfKnown'. This allows the internal Properties instance to be adequately sized & initialized at the beginning of this constructor, alleviating the need / overhead of resizing, again, during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the Properties constructor. When it is more accurate, the Data-Structure operates more efficiently.
        Throws:
        java.io.IOException - if an error occurred when reading from the input stream.
        java.lang.IllegalArgumentException - if the input stream contains a malformed Unicode escape sequence.
        java.lang.NullPointerException - if inStream is null.
        Code:
        Exact Constructor Body:
         super(friendClassBadge);

 this.fromBuilderOrProperties = false;

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

 this.properties.load(inStream);

      • ReadOnlyProperties

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyProperties​(java.io.Reader reader,
                          java.lang.Integer sizeIfKnown)
                   throws java.io.IOException
        Reads a property list (key and element pairs) from the input character stream in a simple line-oriented format.

        Properties are processed in terms of lines. There are two kinds of lines, natural lines and logical lines. A natural line is defined as a line of characters that is terminated either by a set of line terminator characters ('\n' or '\r' or '\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 '\'. 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.

        A natural line that contains only white space characters is considered blank and is ignored. A comment line has an ASCII '#' or '!' as its first non-whitespace character; comment lines are also ignored and do not encode key-element information. In addition to line terminators, this format considers the characters space (' ', '\u005Cu0020'), tab ('\t', '\u005Cu0009'), and form feed ('\f', '\u005Cu000C') to be white space.

        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 effect 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 not 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 2n contiguous backslashes before a line terminator (or elsewhere) encodes n backslashes after escape processing.

        The key contains all of the characters in the line starting with the first non-whitespace character and up to, but not including, the first unescaped '=', ':', 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,

        \:\=

        would be the two-character key ":=". Line terminator characters can be included using '\r' and '\n' escape sequences. Any white space after the key is skipped; if the first non-whitespace character after the key is '=' or ':', 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 "". Once the raw character sequences constituting the key and element are identified, escape processing is performed as described above.

        As an example, each of the following three lines specifies the key "Truth" and the associated element value "Beauty":

        • Truth = Beauty
        • Truth: Beauty
        • Truth :Beuty


        As another example, the following three lines specify a single property: 

        • fruits      apple, banana, pear, \
            cantaloupe, watermelon, \
            kiwi, mango


        The key is "fruits" and the associated element is: 
        "apple, banana, pear, cantaloupe, watermelon, kiwi, mango"
        Note that a space appears before each '\' so that a space will appear after each comma in the final result; the '\', line terminator, and leading white space on the continuation line are merely discarded and are not replaced by one or more other characters.

        As a third example, the line:

        • cheeses


        specifies that the key is "cheeses" and the associated element is the empty string "".

        Characters in keys and elements can be represented in escape sequences similar to those used for character and string literals (see The Java Language Specification section 3.3 and 3.10.6 The differences from the character escape sequences and Unicode escapes used for characters and strings are:

        • Octal escapes are not recognized.
        • The character sequence '\b' does not represent a backspace character.
        • The method does not treat a backslash character, '\', before a non-valid escape character as an error; the backslash is silently dropped. For example, in a Java String the sequence "\z" would cause a compile time error. In contrast, this method silently drops the backslash. Therefore, this method treats the two character sequence "\b" as equivalent to the single character 'b'.
        • 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.
        • Only a single 'u' character is allowed in a Unicode escape sequence.

        The specified stream remains open after this method returns.

        This Detail-Comment was copied from class: java.util.Properties, JDK 21

        Method: Properties.load(InputStream.inStream)
        Parameters:
        reader - the input character stream.
        sizeIfKnown - If the number of elements to be inserted is known, this value / size may be provided, here, to parameter 'sizeIfKnown'. This allows the internal Properties instance to be adequately sized & initialized at the beginning of this constructor, alleviating the need / overhead of resizing, again, during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the Properties constructor. When it is more accurate, the Data-Structure operates more efficiently.
        Throws:
        java.io.IOException - if an error occurred when reading from the input stream.
        java.lang.IllegalArgumentException - if a malformed Unicode escape appears in the input.
        java.lang.NullPointerException - if reader is null.
        Code:
        Exact Constructor Body:
         super(friendClassBadge);

 this.fromBuilderOrProperties = false;

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

 this.properties.load(reader);

      • ReadOnlyProperties

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyProperties​(java.lang.Integer sizeIfKnown,
                          java.io.InputStream in)
                   throws java.io.IOException,
                          java.io.UnsupportedEncodingException,
                          java.util.InvalidPropertiesFormatException
        Loads all of the properties represented by the XML document on the specified input stream into this properties table.

        The XML document must have the following DOCTYPE declaration:

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


        Furthermore, the document must satisfy the properties DTD described above.

        An implementation is required to read XML documents that use the "UTF-8" or "UTF-16" encoding. An implementation may support additional encodings.

        The specified stream is closed after this method returns.

        This Detail-Comment was copied from class: java.util.Properties, JDK 21

        Method: Properties.load(InputStream.inStream)
        Parameters:
        sizeIfKnown - If the number of elements to be inserted is known, this value / size may be provided, here, to parameter 'sizeIfKnown'. This allows the internal Properties instance to be adequately sized & initialized at the beginning of this constructor, alleviating the need / overhead of resizing, again, during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the Properties constructor. When it is more accurate, the Data-Structure operates more efficiently.
        in - the input stream from which to read the XML document.
        Throws:
        java.io.IOException - if reading from the specified input stream results in an IOException.
        java.io.UnsupportedEncodingException - if the document's encoding declaration can be read and it specifies an encoding that is not supported
        java.util.InvalidPropertiesFormatException - Data on input stream does not constitute a valid XML document with the mandated document type.
        java.lang.NullPointerException - if in is null.
        See Also:
        storeToXML(OutputStream, String, String), Character Encoding in Entities
        Code:
        Exact Constructor Body:
         super(friendClassBadge);

 this.fromBuilderOrProperties = false;

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

 this.properties.loadFromXML(in);

      • ReadOnlyProperties

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyProperties​
            (Tuple2<java.lang.Object,​java.lang.Object> refHolder,
             java.lang.Runnable computeNextEntry,
             java.lang.Integer sizeIfKnown)
        Builds a Properties instance using the 'refHolder' & 'computeNextEntry' combination.
        Parameters:
        refHolder - Any instance of Tuple2 may be passed to this parameter. This reference may not be null, or a NullPointerException will throw immediately.

        This parameter must be used to populate this ReadOnlyProperties instance.

        The 'computeNextEntry' instance provided to this method, when invoked, should place each Key-Value Pair that it computes into the two fields of this 'refHolder'. After invoking the 'computeNextEntry' consumer, the contents of this Tuple2 are inserted into this ReadOnlyMap instance.

        Please review the Source-Code in the window below. It, hopefully, elucidates how this method retrieves the data to be placed into this ReadOnlyProperties using this 'refHolder'.
        computeNextEntry - This Runnable instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyProperties instance. The Lambda-Expression or Method provided to this Runnable must place each Key-Value Pair into the 'refHolder' instance.

        After each insertion that is performed, the logic will check if the Key and Value of Tuple2 instance have been passed null. When both the Key and the Value are null, this Constructor will cease inserting data into this instance internal Properties, and exit.

        NOTE: It is acceptabe for this Runnable to return multiple values for a single Key. If redundant Keys are placed into the 'refHolder', the old value assigned to the key will be over-written by the latest value. If both a key and a value placed into 'refHolder' are duplicates, both will be reinserted a second time, which doesn't have any effect on the internally stored Properties.

        Again, for a detailed understanding of how to use this parameter, it is best just to look at the imported Constructor-Body below!
        sizeIfKnown - If the number of elements to be inserted is known, this value / size may be provided, here, to parameter 'sizeIfKnown'. This allows the internal Properties instance to be adequately sized & initialized at the beginning of this constructor, alleviating the need / overhead of resizing, again, during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the Properties constructor. When it is more accurate, the Data-Structure operates more efficiently.
        Code:
        Exact Constructor Body:
         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;

    • Method Detail

      • emptyROP

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static ReadOnlyProperties emptyROP()
        Returns an empty singleton instance of this class.

        NOTE: The instance that is returned is a static, final constant which is constructed during the loading of this class by the Class-Loader. It is fully Thread-Safe, unless it is going to be used as an Object-Monitor to help lock a Synchronized Code-Block!
        Code:
        Exact Method Body:
         return EMPTY_READONLY_PROPERTIES;

      • store

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void store​(java.io.Writer writer,
                  java.lang.String comments)
           throws java.io.IOException
        Writes this property list (key and element pairs) from this instance' internal Properties table to the output character stream (in a format suitable for using the Properties.load(Reader) method.

        Properties from the defaults table of this Properties table (if any) are not written out by this method.

        If the comments argument is not null, then an ASCII '#' character, the comments string, and a line separator are first written to the output stream. Thus, the comments can serve as an identifying comment. Any one of a line feed ('\n'), a carriage return ('\r'), or a carriage return followed immediately by a line feed ('\r\n') in comments is replaced by a System.lineSeparator() and if the next character in comments is not character '#' or character '!' then an ASCII '#' is written out after that line separator.

        If the System-Property java.properties.date is set on the command line and is non-empty (as determined by String.isEmpty(), a comment line is written as follows. First, a '#' character is written, followed by the contents of the property, followed by a line separator. Any line terminator characters in the value of the system property are treated the same way as noted above for the comments argument. If the system property is not set or is empty, a comment line is written as follows. First, a '#' character is written, followed by the current date and time formatted as if by the Date.toString() method, followed by a line separator.

        Then every entry in this Properties table is written out, one per line. For each entry the key string is written, then an ASCII '=', then the associated element string. For the key, all space characters are written with a preceding '\' character. For the element, leading space characters, but not embedded or trailing space characters, are written with a preceding '\' character. The key and element characters '#', '!', '=', and ':' are written with a preceding backslash to ensure that they are properly loaded.

        After the entries have been written, the output stream is flushed. The output stream remains open after this method returns.

        The keys and elements are written in the natural sort order of the keys in the entrySet() unless entrySet() is overridden by a subclass to return a different value than super.entrySet().
        Parameters:
        writer - an output character stream writer.
        comments - a description of the property list.
        Throws:
        java.io.IOException - if writing this property list to the specified output stream throws an IOException.
        java.lang.ClassCastException - if this Properties object contains any keys or values that are not Strings.
        java.lang.NullPointerException - if writer is null.
        Code:
        Exact Method Body:
         this.properties.store(writer, comments);

      • store

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void store​(java.io.OutputStream out,
                  java.lang.String comments)
           throws java.io.IOException
        Writes this property list (key and element pairs) from this instance' internal Properties table to the output character stream in a format suitable for using the Properties.load(InputStream) method.

        Properties from the defaults table of this Properties table (if any) are not written out by this method.

        This method outputs the comments, properties keys and values in the same format as specified in store(Writer) with the following differences:
        • The stream is written using the ISO 8859-1 character encoding.
        • Characters not in Latin-1 in the comments are written as '\u005Cu'xxxx for their appropriate unicode hexadecimal value xxxx.
        • Characters less than \u005Cu0020 and characters greater than '\u005Cu007E' in property keys or values are written as '\u005Cu'xxxx for the appropriate hexadecimal value xxxx.


        After the entries have been written, the output stream is flushed. The output stream remains open after this method returns.
        Parameters:
        out - an output stream.
        comments - a description of the property list.
        Throws:
        java.io.IOException - if writing this property list to the specified output stream throws an IOException.
        java.lang.ClassCastException - if this Properties object contains any keys or values that are not Strings.
        java.lang.NullPointerException - if out is null.
        Code:
        Exact Method Body:
         this.properties.store(out, comments);

      • storeToXML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void storeToXML​(java.io.OutputStream os,
                       java.lang.String comment)
                throws java.io.IOException
        Emits an XML document representing all of the properties contained in this table.

        An invocation of this method of the form props.storeToXML(os, comment) behaves in exactly the same way as the invocation props.storeToXML(os, comment, "UTF-8");.
        Parameters:
        os - the output stream on which to emit the XML document.
        comment - a description of the property list, or null if no comment is desired.
        Throws:
        java.io.IOException - if writing to the specified output stream results in an IOException.
        java.lang.NullPointerException - if os is null.
        java.lang.ClassCastException - if this Properties object contains any keys or values that are not Strings.
        Code:
        Exact Method Body:
         this.properties.storeToXML(os, comment);

      • storeToXML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void storeToXML​(java.io.OutputStream os,
                       java.lang.String comment,
                       java.lang.String encoding)
                throws java.io.IOException
        Emits an XML document representing all of the properties contained in this table, using the specified encoding.

        The XML document will have the following DOCTYPE declaration:

        HTML Elements:
        <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">;


        If the specified comment is null then no comment will be stored in the document.

        An implementation is required to support writing of XML documents that use the "UTF-8" or "UTF-16" encoding. An implementation may support additional encodings.

        The specified stream remains open after this method returns.

        This method behaves the same as storeToXML(OutputStream, String, Charset) except that it will look up the charset using the given encoding name.
        Parameters:
        os - the output stream on which to emit the XML document.
        comment - a description of the property list, or null if no comment is desired.
        encoding - the name of a supported character encoding
        Throws:
        java.io.IOException - if writing to the specified output stream results in an IOException.
        java.io.UnsupportedEncodingException - if the encoding is not supported by the implementation.
        java.lang.NullPointerException - if os is null, or if encoding is null.
        java.lang.ClassCastException - if this Properties object contains any keys or values that are not Strings.
        See Also:
        Character Encoding in Entities
        Code:
        Exact Method Body:
         this.properties.storeToXML(os, comment, encoding);

      • storeToXML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void storeToXML​(java.io.OutputStream os,
                       java.lang.String comment,
                       java.nio.charset.Charset charset)
                throws java.io.IOException
        Emits an XML document representing all of the properties contained in this table, using the specified encoding.

        The XML document will have the following DOCTYPE declaration:

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


        If the specified comment is null then no comment will be stored in the document.

        An implementation is required to support writing of XML documents that use the "UTF-8" or "UTF-16" encoding. An implementation may support additional encodings.

        Unmappable characters for the specified charset will be encoded as numeric character references.

        The specified stream remains open after this method returns.
        Parameters:
        os - the output stream on which to emit the XML document.
        comment - a description of the property list, or null if no comment is desired.
        charset - the charset
        Throws:
        java.io.IOException - if writing to the specified output stream results in an IOException.
        java.lang.NullPointerException - if os or charset is null.
        java.lang.ClassCastException - if this Properties object contains any keys or values that are not Strings.
        See Also:
        Character Encoding in Entities
        Code:
        Exact Method Body:
         this.properties.storeToXML(os, comment, charset);

      • getProperty

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String getProperty​(java.lang.String 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 null if the property is not found.
        Parameters:
        key - the property key.
        Returns:
        the value in this property list with the specified key value.
        Code:
        Exact Method Body:
         return this.properties.getProperty(key);

      • getProperty

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String getProperty​(java.lang.String key,
                                    java.lang.String defaultValue)
        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.
        Parameters:
        key - the hashtable key.
        defaultValue - a default value.
        Returns:
        the value in this property list with the specified key value.
        Code:
        Exact Method Body:
         return this.properties.getProperty(key, defaultValue);

      • propertyNames

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Enumeration<?> propertyNames()
        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.
        Returns:
        an enumeration of all the keys in this property list, including the keys in the default property list.
        Throws:
        java.lang.ClassCastException - if any key in this property list is not a String.
        See Also:
        stringPropertyNames()
        Code:
        Exact Method Body:
         return this.properties.propertyNames();

      • stringPropertyNames

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlySet<java.lang.String> stringPropertyNames()
        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 String are omitted.

        The returned set is not backed by this Properties object. Changes to this Properties object are not reflected in the returned set.
        Returns:
        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.
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(this.properties.stringPropertyNames());

      • list

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void list​(java.io.PrintStream out)
        Prints this property list out to the specified output stream. This method is useful for debugging.
        Parameters:
        out - an output stream.
        Throws:
        java.lang.ClassCastException - if any key in this property list is not a String.
        Code:
        Exact Method Body:
         this.properties.list(out);

      • list

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void list​(java.io.PrintWriter out)
        Prints this property list out to the specified output stream. This method is useful for debugging.
        Parameters:
        out - an output stream.
        Throws:
        java.lang.ClassCastException - if any key in this property list is not a String.
        Code:
        Exact Method Body:
         this.properties.list(out);

      • size

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int size()
        Description copied from class: ReadOnlyHashtable
        Returns the number of keys in this Hashtable.
        Specified by:
        size in interface ReadOnlyDictionary<java.lang.Object,​java.lang.Object>
        Specified by:
        size in interface ReadOnlyMap<java.lang.Object,​java.lang.Object>
        Overrides:
        size in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Returns:
        the number of keys in this Hashtable.
        Code:
        Exact Method Body:
         return this.properties.size();

      • contains

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean contains​(java.lang.Object value)
        Description copied from class: ReadOnlyHashtable
        Tests if some key maps into the specified value in this Hashtable. This operation is more expensive than the containsKey method.

        Note that this method is identical in functionality to containsValue, (which is part of the ReadOnlyMap interface.
        Overrides:
        contains in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Parameters:
        value - a value to search for
        Returns:
        TRUE if and only if some key maps to the value argument in this Hashtable as determined by the equals method; false otherwise.
        Code:
        Exact Method Body:
         return this.properties.contains(value);

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.Object get​(java.lang.Object key)
        Description copied from class: ReadOnlyHashtable
        Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.

        More formally, if this map contains a mapping from a key k to a value v such that (key.equals(k)), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)
        Specified by:
        get in interface ReadOnlyDictionary<java.lang.Object,​java.lang.Object>
        Specified by:
        get in interface ReadOnlyMap<java.lang.Object,​java.lang.Object>
        Overrides:
        get in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        the value to which the specified key is mapped, or null if this map contains no mapping for the key
        Code:
        Exact Method Body:
         return this.properties.get(key);

      • keySet

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlySet<java.lang.Object> keySet()
        Description copied from class: ReadOnlyHashtable
        Returns a ReadOnlySet view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa.
        Specified by:
        keySet in interface ReadOnlyMap<java.lang.Object,​java.lang.Object>
        Overrides:
        keySet in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Returns:
        a set view of the keys contained in this map
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(
     fromBuilderOrProperties
         ? ((ROPropertiesBuilder) this.properties)._keySet(friendClassBadge)
         : this.properties.keySet()
 );

      • values

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlyCollection<java.lang.Object> values()
        Description copied from class: ReadOnlyHashtable
        Returns a ReadOnlyCollection view of the values contained in this map.
        Specified by:
        values in interface ReadOnlyMap<java.lang.Object,​java.lang.Object>
        Overrides:
        values in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Returns:
        a collection view of the values contained in this map
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyCollection<>(
     fromBuilderOrProperties
         ? ((ROPropertiesBuilder) this.properties)._values(friendClassBadge)
         : this.properties.values()
 );

      • entrySet

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlySet<ReadOnlyMap.Entry<java.lang.Object,​java.lang.Object>> entrySet
            ()
        Description copied from class: ReadOnlyHashtable
        Returns a ReadOnlySet view of the mappings contained in this map.
        Specified by:
        entrySet in interface ReadOnlyMap<java.lang.Object,​java.lang.Object>
        Overrides:
        entrySet in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Returns:
        a set view of the mappings contained in this map
        Code:
        Exact Method Body:
         return ROHelperEntrySet.toReadOnlyEntrySet(
     fromBuilderOrProperties
         ? ((ROPropertiesBuilder) this.properties)._entrySet(friendClassBadge)
         : this.properties.entrySet()
 );

      • getOrDefault

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.Object getOrDefault​(java.lang.Object key,
                                     java.lang.Object defaultValue)
        Description copied from interface: ReadOnlyMap
        Returns the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key.
        Specified by:
        getOrDefault in interface ReadOnlyMap<java.lang.Object,​java.lang.Object>
        Overrides:
        getOrDefault in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Parameters:
        key - the key whose associated value is to be returned
        defaultValue - the default mapping of the key
        Returns:
        the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key
        Code:
        Exact Method Body:
         return this.properties.getOrDefault(key, defaultValue);

      • forEach

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void forEach​
            (java.util.function.BiConsumer<? super java.lang.Object,​? super java.lang.Object> action)
        Description copied from interface: ReadOnlyMap
        Performs the given action for each entry in this map until all entries have been processed or the action throws an exception. Unless otherwise specified by the implementing class, actions are performed in the order of entry set iteration (if an iteration order is specified.) Exceptions thrown by the action are relayed to the caller.

        The default implementation is equivalent to, for this map: 

         for (ReadOnlyMap.Entry<K, V> entry : map.entrySet())
     action.accept(entry.getKey(), entry.getValue());


        The default implementation makes no guarantees about synchronization or atomicity properties of this method. Any implementation providing atomicity guarantees must override this method and document its concurrency properties.
        Specified by:
        forEach in interface ReadOnlyMap<java.lang.Object,​java.lang.Object>
        Overrides:
        forEach in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Parameters:
        action - The action to be performed for each entry
        Code:
        Exact Method Body:
         this.properties.forEach(action);

      • cloneToProperties

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Properties cloneToProperties()
        Clone's 'this' instance internal Properties field, and returns it. This method generates a Read / Write Cloned Version of 'this' instance' internal ReadOnlyProperties. The instance that's returned by this method is a clone, and this decision preserves the immutable (Read-Only) protection offered by this class.

        Standard JDK Properties
        The returned object is a Standard JDK Properties data-structure (the one from package java.util). It is mutable, but again because it is a clone of 'this' instance's internal Properties, it is not actually 'linked' to the internal Properties

        This does mean that changes to the returned Properties instance will not be reflected to the 'this' ReadOnlyProperties. They are, in fact, two independent and unlinked copies of the internal data.
        Returns:
        An independent, mutable copy of 'this' instance' internal Properties data-structure.
        Code:
        Exact Method Body:
         return fromBuilderOrProperties
     ? new Properties(this.properties)
     : (Properties) this.properties.clone();

      • cloneToMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map<java.lang.Object,​java.lang.Object> cloneToMap()
        Converts this ReadOnlyProperties to a java.util.Properties
        Same: Identical to the method cloneToProperties().
        Returns: Has Return-Type Map<E>, instead.
        Implements: Parent-Class ReadOnlyMap.cloneToMap()
        Specified by:
        cloneToMap in interface ReadOnlyMap<java.lang.Object,​java.lang.Object>
        Overrides:
        cloneToMap in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Returns:
        • For the sub-class ReadOnlyHashMap, this will return a cloned instance of the internal java.util.HashMap.

        • For the sub-class ReadOnlyTreeMap, this will return a cloned instance of the internal java.util.TreeMap.

        • For the sub-class ReadOnlyHashtable, this will return a cloned instance of the internal java.util.Hashtable.

        • For the sub-class ReadOnlyProperties, this will return a cloned instance of the internal java.util.Properties.
        Code:
        Exact Method Body:
         return cloneToProperties();

      • wrapToImmutableMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map<java.lang.Object,​java.lang.Object> wrapToImmutableMap
            ()
        Description copied from interface: ReadOnlyMap
        Invokes java.util.Collections.unmodifiableMap on the internal Map

        Standard JDK Map:
        There may be situations where the Type ReadOnlyMap is simply not usable with an API that can't be adapted to accept Type's from the Java-HTML ReadOnly Package. If such a case arises, this method can be used to generate an immutable instance of a JDK-Standard java.util Type, which does not inherit from Torello.Java.ReadOnly

        Class java.util.Collections offers a method that wraps a type into an Unmodifiable-Wrapper that implements the standard java.util.Map, but throws an exception if any attempts are made to invoke Mutator-Methods.

        Unmodifiable-Collections throw Exceptions instead:
        The returned java.util.Map instance will hopefully provide an acceptable substitute when ReadOnly Type's cannot match an API's requirements. Java's Immutable-Wrappers work on a different principle - these classes retain any / all Mutator-Methods amongst their Type-Members, but instead throw an UnsupportedOperationException if any of those methods are invoked!

        Also, if a Java Collections Framework Unmodifiable-Class has any Member-Methods that return a "View" into the underlying Data-Structure, the Sub-Lists and Sub-Maps returned by those methods are also, subsequently, wrapped in an Unmodifiable-Wrapper. These returned instances will also throw an UnsupportedOperationException if any of those methods are invoked!

        This does provide a shield or layer of protection against modification to guarantee the "Immutability-Contract" offered by these classes, all-the-while returning to native Java API Collection Types, rather than Torello.Java.ReadOnly Types, which may not always be compatible with a given API or Interface requirement!

        Remember, many of the Data-Classes inside java.util have methods whose documentation state very clearly that "any changes made the this [View] will be pushed back into the original type."
        Specified by:
        wrapToImmutableMap in interface ReadOnlyMap<java.lang.Object,​java.lang.Object>
        Overrides:
        wrapToImmutableMap in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Returns:
        A Set which adheres to the JDK interface java.util.Set, but throws an UnsupportedOperationException if a user attempts to invoke a Mutator-Method on the returned instance.
        Code:
        Exact Method Body:
         return Collections.unmodifiableMap(this.properties);

      • toString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Returns a String representation of this Properties. The String representation consists of a list of the collection's elements in the order they are returned by its iterator, enclosed in square brackets ("[]"). Adjacent elements are separated by the characters ", " (comma and space). Elements are converted to String's as by String.valueOf(Object).
        Overrides:
        toString in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Returns:
        a String representation of this Properties
        Code:
        Exact Method Body:
         return this.properties.toString();

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object o)
        Compares the specified Object with this List for equality, as per the definition in the class java.util.Properties.
        Specified by:
        equals in interface ReadOnlyMap<java.lang.Object,​java.lang.Object>
        Overrides:
        equals in class ReadOnlyHashtable<java.lang.Object,​java.lang.Object>
        Parameters:
        o - object to be compared for equality with this Properties
        Returns:
        TRUE if the specified Object is equal to this map
        Code:
        Exact Method Body:
         if (this == o) return true;
 if (! (o instanceof ReadOnlyProperties)) return false;
 return this.properties.equals(((ReadOnlyProperties) o).properties);