Summary

Clarify the system properties used to construct the default locale

Problem

There is no public description of how the default locale is constructed, especially the role for undocumented, but commonly used/overridden system properties.

Solution

Add a new section in java.util.Locale class description about "Default Locale" with the explanation for the following system properties and how they are established, including implementation-specific -D command line overrides:

• user.language
• user.script
• user.country
• user.variant
• user.extensions

Also, mention those finer-grained system properties that are provided for each Locale.Category.

Specification

Add the following section in the java.util.Locale class description:

+  * <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/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 {@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.
+  *

Modify the method descriptions for Locale.get/setDefault({Category}) as follows:

public static Locale getDefault()

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

public static Locale getDefault(Locale.Category)

      /**
-      * 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
       * @return the default locale for the specified Category for this instance
       *     of the Java Virtual Machine

public static void setDefault(Locale)

      /**
-      * 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")}
       * permission before the default locale is changed.
       * <p>

public static void setDefault(Locale.Category, Locale)

      /**
-      * 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
       * the default locale is changed.
       * <p>