diff --git a/src/java.base/share/classes/java/util/Locale.java b/src/java.base/share/classes/java/util/Locale.java index 8fac36fb84f..726fa7c22fc 100644 --- a/src/java.base/share/classes/java/util/Locale.java +++ b/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. * + *
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: + *
Locale-related System Properties Key | + *Description |
---|---|
{@systemProperty user.language} | + *{@link ##def_language language} for the default Locale, + * such as "en" (English) |
{@systemProperty user.script} | + *{@link ##def_script script} for the default Locale, + * such as "Latn" (Latin) |
{@systemProperty user.country} | + *{@link ##def_region country} for the default Locale, + * such as "US" (United States) |
{@systemProperty user.variant} | + *{@link ##def_variant variant} for the default Locale, + * such as "POSIX" |
{@systemProperty user.extensions} | + *{@link ##def_extensions extensions} for the default Locale, + * such as "u-ca-japanese" (Japanese Calendar) |
Altering the system property values with {@link System#setProperties(Properties)}/ + * {@link System#setProperty(String, String)} has no effect on the default Locale. + *
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. + * + *
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. + * *
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. *
* 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. *
* 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
* 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.
*
* If there is a security manager, its checkPermission method is called
* with a PropertyPermission("user.language", "write") permission before