Skip to content

Commit

Permalink
8320919: Clarify Locale related system properties
Browse files Browse the repository at this point in the history
Reviewed-by: smarks, rriggs
  • Loading branch information
naotoj committed Jan 9, 2024
1 parent a5071e0 commit 376051a
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
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 @@ -258,6 +259,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 @@ -984,14 +1053,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 @@ -1001,13 +1070,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 @@ -1108,8 +1177,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 @@ -1142,8 +1212,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

3 comments on commit 376051a

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@naotoj
Copy link
Member Author

@naotoj naotoj commented on 376051a Jan 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/backport jdk22

@openjdk
Copy link

@openjdk openjdk bot commented on 376051a Jan 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@naotoj the backport was successfully created on the branch backport-naotoj-376051a9 in my personal fork of openjdk/jdk22. To create a pull request with this backport targeting openjdk/jdk22:master, just click the following link:

➡️ Create pull request

The title of the pull request is automatically filled in correctly and below you find a suggestion for the pull request body:

Hi all,

This pull request contains a backport of commit 376051a9 from the openjdk/jdk repository.

The commit being backported was authored by Naoto Sato on 9 Jan 2024 and was reviewed by Stuart Marks and Roger Riggs.

Thanks!

If you need to update the source branch of the pull then run the following commands in a local clone of your personal fork of openjdk/jdk22:

$ git fetch https://github.com/openjdk-bots/jdk22.git backport-naotoj-376051a9:backport-naotoj-376051a9
$ git checkout backport-naotoj-376051a9
# make changes
$ git add paths/to/changed/files
$ git commit --message 'Describe additional changes made'
$ git push https://github.com/openjdk-bots/jdk22.git backport-naotoj-376051a9

Please sign in to comment.