8320919: Clarify Locale related system properties

Reviewed-by: iris
Backport-of: 376051a9be95e0e4acf3c59d0eba3e9ef8727d79

Author: naotoj

src/java.base/share/classes/java/util/Locale.java

@@ -45,6 +45,7 @@
 import java.io.ObjectOutputStream;
 import java.io.ObjectStreamField;
 import java.io.Serializable;
+import java.text.DateFormat;
 import java.text.MessageFormat;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.spi.LocaleNameProvider;
@@ -257,6 +258,74 @@
  * locales. For example, {@code Locale.US} is the {@code Locale} object
  * for the United States.
  *
+ * <h3><a id="default_locale">Default Locale</a></h3>
+ *
+ * <p>The default Locale is provided for any locale-sensitive methods if no
+ * {@code Locale} is explicitly specified as an argument, such as
+ * {@link DateFormat#getInstance()}. The default Locale is determined at startup
+ * of the Java runtime and established in the following three phases:
+ * <ol>
+ * <li>The locale-related system properties listed below are established from the
+ * host environment. Some system properties (except for {@code user.language}) may
+ * not have values from the host environment.
+ * <table class="striped">
+ * <caption style="display:none">Shows property keys and associated values</caption>
+ * <thead>
+ * <tr><th scope="col">Locale-related System Properties Key</th>
+ *     <th scope="col">Description</th></tr>
+ * </thead>
+ * <tbody>
+ * <tr><th scope="row">{@systemProperty user.language}</th>
+ *     <td>{@link ##def_language language} for the default Locale,
+ *     such as "en" (English)</td></tr>
+ * <tr><th scope="row">{@systemProperty user.script}</th>
+ *     <td>{@link ##def_script script} for the default Locale,
+ *     such as "Latn" (Latin)</td></tr>
+ * <tr><th scope="row">{@systemProperty user.country}</th>
+ *     <td>{@link ##def_region country} for the default Locale,
+ *     such as "US" (United States)</td></tr>
+ * <tr><th scope="row">{@systemProperty user.variant}</th>
+ *     <td>{@link ##def_variant variant} for the default Locale,
+ *     such as "POSIX"</td></tr>
+ * <tr><th scope="row">{@systemProperty user.extensions}</th>
+ *     <td>{@link ##def_extensions extensions} for the default Locale,
+ *     such as "u-ca-japanese" (Japanese Calendar)</td></tr>
+ * </tbody>
+ * </table>
+ * </li>
+ * <li>The values of these system properties can be overridden by values designated
+ * at startup time. If the overriding value of the {@code user.extensions} property
+ * is unparsable, it is ignored. The overriding values of other properties are not
+ * checked for syntax or validity and are used directly in the default Locale.
+ * (Typically, system property values can be provided using the {@code -D} command-line
+ * option of a launcher. For example, specifying {@code -Duser.extensions=foobarbaz}
+ * results in a default Locale with no extensions, while specifying
+ * {@code -Duser.language=foobarbaz} results in a default Locale whose language is
+ * "foobarbaz".)
+ * </li>
+ * <li>The default {@code Locale} instance is constructed from the values of these
+ * system properties.
+ * </li>
+ * </ol>
+ * <p>Altering the system property values with {@link System#setProperties(Properties)}/
+ * {@link System#setProperty(String, String)} has no effect on the default Locale.
+ * <p>Once the default Locale is established, applications can query the default
+ * Locale with {@link #getDefault()} and change it with {@link #setDefault(Locale)}.
+ * If the default Locale is changed with {@link #setDefault(Locale)}, the corresponding
+ * system properties are not altered. It is not recommended that applications read
+ * these system properties and parse or interpret them as their values may be out of date.
+ *
+ * <p>There are finer-grained default Locales specific for each {@link Locale.Category}.
+ * These category specific default Locales can be queried by {@link #getDefault(Category)},
+ * and set by {@link #setDefault(Category, Locale)}. Construction of these category
+ * specific default Locales are determined by the corresponding system properties,
+ * which consist of the base system properties as listed above, suffixed by either
+ * {@code ".display"} or {@code ".format"} depending on the category. For example,
+ * the value of the {@code user.language.display} system property will be used in the
+ * {@code language} part of the default Locale for the {@link Locale.Category#DISPLAY}
+ * category. In the absence of category specific system properties, the "category-less"
+ * system properties are used, such as {@code user.language} in the previous example.
+ *
  * <h3><a id="LocaleMatching">Locale Matching</a></h3>
  *
  * <p>If an application or a system is internationalized and provides localized
@@ -983,14 +1052,14 @@ public int hashCode() {
     }
 
     /**
-     * Gets the current value of the default locale for this instance
-     * of the Java Virtual Machine.
+     * Gets the current value of the {@link ##default_locale default locale} for
+     * this instance of the Java Virtual Machine.
      * <p>
      * The Java Virtual Machine sets the default locale during startup
      * based on the host environment. It is used by many locale-sensitive
      * methods if no locale is explicitly specified.
      * It can be changed using the
-     * {@link #setDefault(java.util.Locale) setDefault} method.
+     * {@link #setDefault(Locale)} method.
      *
      * @return the default locale for this instance of the Java Virtual Machine
      */
@@ -1000,13 +1069,13 @@ public static Locale getDefault() {
     }
 
     /**
-     * Gets the current value of the default locale for the specified Category
-     * for this instance of the Java Virtual Machine.
+     * Gets the current value of the {@link ##default_locale default locale} for
+     * the specified Category for this instance of the Java Virtual Machine.
      * <p>
      * The Java Virtual Machine sets the default locale during startup based
      * on the host environment. It is used by many locale-sensitive methods
      * if no locale is explicitly specified. It can be changed using the
-     * setDefault(Locale.Category, Locale) method.
+     * {@link #setDefault(Locale.Category, Locale)} method.
      *
      * @param category the specified category to get the default locale
      * @throws NullPointerException if category is null
@@ -1114,8 +1183,9 @@ private static Optional<LocaleExtensions> getDefaultExtensions(String extensions
     }
 
     /**
-     * Sets the default locale for this instance of the Java Virtual Machine.
-     * This does not affect the host locale.
+     * Sets the {@link ##default_locale default locale} for
+     * this instance of the Java Virtual Machine. This does not affect the
+     * host locale.
      * <p>
      * If there is a security manager, its {@code checkPermission}
      * method is called with a {@code PropertyPermission("user.language", "write")}
@@ -1148,8 +1218,9 @@ public static synchronized void setDefault(Locale newLocale) {
     }
 
     /**
-     * Sets the default locale for the specified Category for this instance
-     * of the Java Virtual Machine. This does not affect the host locale.
+     * Sets the {@link ##default_locale default locale} for the specified
+     * Category for this instance of the Java Virtual Machine. This does
+     * not affect the host locale.
      * <p>
      * If there is a security manager, its checkPermission method is called
      * with a PropertyPermission("user.language", "write") permission before