--- old/src/share/classes/java/util/Properties.java 2012-01-23 09:34:34.000000000 -0800
+++ new/src/share/classes/java/util/Properties.java 2012-01-23 09:34:34.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1995, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2012, 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
@@ -37,8 +37,8 @@
import java.lang.reflect.*;
/**
- * The Properties
class represents a persistent set of
- * properties. The Properties
can be saved to a stream
+ * 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.
*
@@ -46,17 +46,17 @@ * "defaults"; this second property list is searched if * the property key is not found in the original property list. *
- * Because Properties
inherits from Hashtable
, the
- * put
and putAll
methods can be applied to a
- * Properties
object. Their use is strongly discouraged as they
+ * 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
- * Strings
. The setProperty
method should be used
- * instead. If the store
or save
method is called
- * on a "compromised" Properties
object that contains a
- * non-String
key or value, the call will fail. Similarly,
- * the call to the propertyNames
or list
method
- * will fail if it is called on a "compromised" Properties
- * object that contains a non-String
key.
+ * {@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.
*
*
* The {@link #load(java.io.Reader) load(Reader)} /
@@ -146,15 +146,15 @@
}
/**
- * Calls the Hashtable method put
. Provided for
+ * Calls the Hashtable method {@code put}. Provided for
* parallelism with the getProperty method. Enforces use of
* strings for property keys and values. The value returned is the
- * result of the Hashtable call to put
.
+ * result of the Hashtable call to {@code put}.
*
* @param key the key to be placed into this property list.
* @param value the value corresponding to key.
* @return the previous value of the specified key in this property
- * list, or null
if it did not have one.
+ * list, or {@code null} if it did not have one.
* @see #getProperty
* @since 1.2
*/
@@ -171,13 +171,13 @@
* kinds of line, 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
)
+ * 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
- * \
. Note that a comment line cannot be extended
+ * {@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.
@@ -185,13 +185,13 @@
*
* 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-white
+ * {@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
- * (' '
, '\u0020'
), tab
- * ('\t'
, '\u0009'
), and form feed
- * ('\f'
, '\u000C'
) to be white
+ * ({@code ' '}, {@code '\u005Cu0020'}), tab
+ * ({@code '\t'}, {@code '\u005Cu0009'}), and form feed
+ * ({@code '\f'}, {@code '\u005Cu000C'}) to be white
* space.
*
*
@@ -215,31 +215,31 @@ *
* 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 '='
,
- * ':'
, or white space character other than a line
+ * 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,
*
- * \:\=
+ * {@code \:\=}
*
- * would be the two-character key ":="
. Line
- * terminator characters can be included using \r
and
- * \n
escape sequences. Any white space after the
+ * 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 '='
or ':'
, then it is
+ * 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
- * ""
. Once the raw character sequences
+ * {@code ""}. 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"
:
+ * {@code "Truth"} and the associated element value
+ * {@code "Beauty"}:
*
*
* Truth = Beauty @@ -254,11 +254,11 @@ * cantaloupe, watermelon, \ * kiwi, mango *- * The key is
"fruits"
and the associated element is:
+ * The key is {@code "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 \
,
+ * 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 not replaced by one or more other
* characters.
@@ -267,8 +267,8 @@
* *
cheeses *- * specifies that the key is
"cheeses"
and the associated
- * element is the empty string ""
.+ * specifies that the key is {@code "cheeses"} and the associated + * element is the empty string {@code ""}.
*
\b
does not
+ * \
, before a non-valid escape character as an
+ * {@code \}, 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
+ * 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 "\b"
as equivalent to the single
- * character 'b'
.
+ * sequence {@code "\b"} as equivalent to the single
+ * character {@code 'b'}.
*
* store(OutputStream out, String comments)
method
+ * Calls the {@code store(OutputStream out, String comments)} method
* and suppresses IOExceptions that were thrown.
*
* @deprecated This method does not throw an IOException if an I/O error
* occurs while saving the property list. The preferred way to save a
- * properties list is via the store(OutputStream out,
- * String comments)
method or the
- * storeToXML(OutputStream os, String comment)
method.
+ * properties list is via the {@code store(OutputStream out,
+ * String comments)} method or the
+ * {@code storeToXML(OutputStream os, String comment)} method.
*
* @param out an output stream.
* @param comments a description of the property list.
- * @exception ClassCastException if this Properties
object
+ * @exception ClassCastException if this {@code Properties} object
* contains any keys or values that are not
- * Strings
.
+ * {@code Strings}.
*/
@Deprecated
public void save(OutputStream out, String comments) {
@@ -714,37 +714,37 @@
/**
* Writes this property list (key and element pairs) in this
- * Properties
table to the output character stream in a
+ * {@code Properties} table to the output character stream in a
* format suitable for using the {@link #load(java.io.Reader) load(Reader)}
* method.
*
- * Properties from the defaults table of this Properties
+ * Properties from the defaults table of this {@code Properties}
* table (if any) are not written out by this method.
*
- * If the comments argument is not null, then an ASCII #
+ * If the comments argument is not null, then an ASCII {@code #}
* character, the comments string, and a line separator are first written
- * to the output stream. Thus, the comments
can serve as an
+ * to the output stream. Thus, the {@code 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
- * in comments is replaced by a line separator generated by the Writer
- * and if the next character in comments is not character #
or
- * character !
then an ASCII #
is written out
+ * in comments is replaced by a line separator generated by the {@code Writer}
+ * and if the next character in comments is not character {@code #} or
+ * character {@code !} then an ASCII {@code #} is written out
* after that line separator.
*
* Next, a comment line is always written, consisting of an ASCII
- * #
character, the current date and time (as if produced
- * by the toString
method of Date
for the
- * current time), and a line separator as generated by the Writer
.
+ * {@code #} character, the current date and time (as if produced
+ * by the {@code toString} method of {@code Date} for the
+ * current time), and a line separator as generated by the {@code Writer}.
*
- * Then every entry in this Properties
table is
+ * Then every entry in this {@code Properties} table is
* written out, one per line. For each entry the key string is
- * written, then an ASCII =
, then the associated
+ * written, then an ASCII {@code =}, then the associated
* element string. For the key, all space characters are
- * written with a preceding \
character. For the
+ * written with a preceding {@code \} 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
+ * space characters, are written with a preceding {@code \}
+ * character. The key and element characters {@code #},
+ * {@code !}, {@code =}, and {@code :} are written
* with a preceding backslash to ensure that they are properly loaded.
*
* After the entries have been written, the output stream is flushed.
@@ -755,9 +755,9 @@
* @param comments a description of the property list.
* @exception IOException if writing this property list to the specified
* output stream throws an IOException.
- * @exception ClassCastException if this Properties
object
- * contains any keys or values that are not Strings
.
- * @exception NullPointerException if writer
is null.
+ * @exception ClassCastException if this {@code Properties} object
+ * contains any keys or values that are not {@code Strings}.
+ * @exception NullPointerException if {@code writer} is null.
* @since 1.6
*/
public void store(Writer writer, String comments)
@@ -771,11 +771,11 @@
/**
* Writes this property list (key and element pairs) in this
- * Properties
table to the output stream in a format suitable
- * for loading into a Properties
table using the
+ * {@code Properties} table to the output stream in a format suitable
+ * for loading into a {@code Properties} table using the
* {@link #load(InputStream) load(InputStream)} method.
*
- * Properties from the defaults table of this Properties
+ * Properties from the defaults table of this {@code Properties}
* table (if any) are not written out by this method.
*
* This method outputs the comments, properties keys and values in @@ -786,12 +786,12 @@ *
\u
xxxx for their appropriate unicode
+ * {@code \u005Cu}xxxx for their appropriate unicode
* hexadecimal value xxxx.
*
- * \u0020
and characters greater
- * than \u007E
in property keys or values are written
- * as \u
xxxx for the appropriate hexadecimal
+ *
@@ -802,9 +802,9 @@
* @param comments a description of the property list.
* @exception IOException if writing this property list to the specified
* output stream throws an IOException.
- * @exception ClassCastException if this Properties
object
- * contains any keys or values that are not Strings
.
- * @exception NullPointerException if out
is null.
+ * @exception ClassCastException if this {@code Properties} object
+ * contains any keys or values that are not {@code Strings}.
+ * @exception NullPointerException if {@code out} is null.
* @since 1.2
*/
public void store(OutputStream out, String comments)
@@ -857,7 +857,7 @@
* results in an IOException.
* @throws InvalidPropertiesFormatException Data on input stream does not
* constitute a valid XML document with the mandated document type.
- * @throws NullPointerException if in
is null.
+ * @throws NullPointerException if {@code in} is null.
* @see #storeToXML(OutputStream, String, String)
* @since 1.5
*/
@@ -879,14 +879,14 @@
* 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 null
+ * @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 IOException.
- * @throws NullPointerException if os
is null.
- * @throws ClassCastException if this Properties
object
+ * @throws NullPointerException if {@code os} is null.
+ * @throws ClassCastException if this {@code Properties} object
* contains any keys or values that are not
- * Strings
.
+ * {@code Strings}.
* @see #loadFromXML(InputStream)
* @since 1.5
*/
@@ -907,13 +907,13 @@
* <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
*
*
- *
If the specified comment is null
then no comment
+ *
If the specified comment is {@code null} then no comment * will be stored in the document. * *
The specified stream remains open after this method returns.
*
* @param os the output stream on which to emit the XML document.
- * @param comment a description of the property list, or null
+ * @param comment a description of the property list, or {@code null}
* if no comment is desired.
* @param encoding the name of a supported
*
@@ -921,11 +921,11 @@
*
* @throws IOException if writing to the specified output stream
* results in an IOException.
- * @throws NullPointerException if os
is null
,
- * or if encoding
is null
.
- * @throws ClassCastException if this Properties
object
+ * @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
- * Strings
.
+ * {@code Strings}.
* @see #loadFromXML(InputStream)
* @since 1.5
*/
@@ -941,7 +941,7 @@
* 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.
+ * {@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.