Skip to content

Commit

Permalink
8320919: Clarify Locale related system properties
Browse files Browse the repository at this point in the history 
Reviewed-by: iris
Backport-of: 376051a9be95e0e4acf3c59d0eba3e9ef8727d79
  • Loading branch information
@naotoj
naotoj committed Jan 10, 2024
1 parent 70a92a7 commit df22632
Showing 1 changed file with 81 additions and 10 deletions.
91 changes: 81 additions & 10 deletions src/java.base/share/classes/java/util/Locale.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
*/
Expand All @@ -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
Expand Down Expand Up @@ -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")}
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit df22632

Please sign in to comment.