Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

8320919: Clarify Locale related system properties #17065

Closed

Conversation

naotoj
Copy link
Member

@naotoj naotoj commented Dec 11, 2023

This is a doc change to clarify what the Default Locale is, and how it is established during the system startup using the system properties. Those locale-related system properties have existed since the early days of Java, but have never been publicly documented before. It is also the intention of this PR to clarify those system properties and how they are overridden. A corresponding CSR has been drafted.


Progress

  • Change must be properly reviewed (1 review required, with at least 1 Reviewer)
  • Change must not contain extraneous whitespace
  • Commit message must refer to an issue
  • Change requires CSR request JDK-8321055 to be approved

Issues

  • JDK-8320919: Clarify Locale related system properties (Bug - P4)
  • JDK-8321055: Clarify Locale related system properties (CSR)

Reviewers

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/17065/head:pull/17065
$ git checkout pull/17065

Update a local copy of the PR:
$ git checkout pull/17065
$ git pull https://git.openjdk.org/jdk.git pull/17065/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 17065

View PR using the GUI difftool:
$ git pr show -t 17065

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/17065.diff

Webrev

Link to Webrev Comment

@bridgekeeper
Copy link

bridgekeeper bot commented Dec 11, 2023

👋 Welcome back naoto! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

@openjdk openjdk bot added csr Pull request needs approved CSR before integration rfr Pull request is ready for review labels Dec 11, 2023
@openjdk
Copy link

openjdk bot commented Dec 11, 2023

@naotoj The following labels will be automatically applied to this pull request:

  • core-libs
  • i18n

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

@openjdk openjdk bot added core-libs core-libs-dev@openjdk.org i18n i18n-dev@openjdk.org labels Dec 11, 2023
@mlbridge
Copy link

mlbridge bot commented Dec 11, 2023

Copy link
Member

@justin-curtis-lu justin-curtis-lu left a comment

Choose a reason for hiding this comment

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

LGTM; left some minor wording comments.

src/java.base/share/classes/java/util/Locale.java Outdated Show resolved Hide resolved
src/java.base/share/classes/java/util/Locale.java Outdated Show resolved Hide resolved
src/java.base/share/classes/java/util/Locale.java Outdated Show resolved Hide resolved
* 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
Copy link
Member

Choose a reason for hiding this comment

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

IIUC, should it be all system properties, not some if we are defining the single exception?

Copy link
Member Author

Choose a reason for hiding this comment

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

The host-dependent part of the code always generates at least the language, thus it was excluded.

src/java.base/share/classes/java/util/Locale.java Outdated Show resolved Hide resolved
* 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
Copy link
Member

Choose a reason for hiding this comment

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

Do these last two sentences need to be enclosed in a parentheses? It seems pretty important as it is the main way to override the properties via command-line.

Copy link
Member Author

Choose a reason for hiding this comment

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

The -D command-line option is not a part of the Java SE specification but an allowed behavior, so it may not be a normative description here.

Copy link
Member

Choose a reason for hiding this comment

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

Right, I suggested putting that in parentheses. Historically we haven't been very formal about distinguishing between normative (Java SE) specifications and informative text that talks about implementations. In this case I felt that enclosing the text in parentheses and also adding hedging words ("typically") made it clear that this text isn't normative.

Copy link
Member

Choose a reason for hiding this comment

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

FWIW, for the FFM API, we describe the --enable-native-access command line flag in a separate @implNote:

* @implNote
* In the reference implementation, access to restricted methods can be granted to
* specific modules using the command line option {@code --enable-native-access=M1,M2, ... Mn},
* where {@code M1}, {@code M2}, {@code ... Mn} are module names (for the unnamed module,
* the special value {@code ALL-UNNAMED} can be used). If this option is specified,
* access to restricted methods are only granted to the modules listed by that option.
* If this option is not specified, access to restricted methods is enabled for all
* modules, but access to restricted methods will result in runtime warnings.

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks for the suggestion, Jorn. I tried embedding @implNote within the ordered list, but looks like it is not allowed. It would be nice if we could use it inside a list, but since it is about overriding the property values, I would rather not have the description apart from that list item.

* {@code -Duser.language=foobarbaz} results in a default Locale whose language is
* "foobarbaz".)
* </li>
* <li>The default {@code Locale} instance is constructed from these system
Copy link
Member

Choose a reason for hiding this comment

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

Might read better as "... is constructed from the values of these system properties."

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks. modified

* 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 sync.
Copy link
Member

Choose a reason for hiding this comment

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

Small wordsmithing: I would say "out of date" instead.

* 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, appended by either
Copy link
Member

Choose a reason for hiding this comment

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

"appended" => "suffixed"

Copy link
Member

@stuart-marks stuart-marks left a comment

Choose a reason for hiding this comment

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

Looks good, with a couple small wording changes.

@naotoj
Copy link
Member Author

naotoj commented Dec 13, 2023

Thanks, Stuart. Modified the wordings as suggested.

* 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.
Copy link
Contributor

Choose a reason for hiding this comment

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

"parse/interpret" -> "parse or interpret".

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks, Roger. Modified.

Comment on lines +302 to +305
* 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".)
Copy link
Contributor

Choose a reason for hiding this comment

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

The parenthesized sentence is so long that its not effective in making it seem like an option.
The "Typical," is sufficient to indicate it is not part of the spec. Drop the parens.

@@ -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 mainly provided for any locale-sensitive methods if no
Copy link
Contributor

Choose a reason for hiding this comment

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

The word "mainly" can be omitted, it doesn't add any clarity.

Copy link
Member Author

Choose a reason for hiding this comment

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

Removed.

Comment on lines 326 to 327
* {@code language} part of the default Locale for {@link Locale.Category#DISPLAY}
* category. In the absence of category specific system properties, the "category-less"
Copy link
Member

Choose a reason for hiding this comment

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

"...part of the default Locale for the Locale.Category#DISPLAY category."
?

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks, Brent. Inserted the

@naotoj naotoj force-pushed the JDK-8320919-Locale-system-properties branch from e67585e to 4a76c89 Compare December 18, 2023 17:41
@openjdk
Copy link

openjdk bot commented Dec 18, 2023

@naotoj Please do not rebase or force-push to an active PR as it invalidates existing review comments. Note for future reference, the bots always squash all changes into a single commit automatically as part of the integration. See OpenJDK Developers’ Guide for more information.

@openjdk
Copy link

openjdk bot commented Jan 9, 2024

@naotoj This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8320919: Clarify Locale related system properties

Reviewed-by: smarks, rriggs

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 160 new commits pushed to the master branch:

  • aba1933: 8323210: Update the usage of cmsFLAGS_COPY_ALPHA
  • f3be138: 8322809: SystemModulesMap::classNames and moduleNames arrays do not match the order
  • bc05893: 8323318: Remove unused Space::is_free_block
  • dd8ae61: 8322237: Heap dump contains duplicate thread records for mounted virtual threads
  • ee98d26: 8323066: gc/g1/TestSkipRebuildRemsetPhase.java fails with 'Skipping Remembered Set Rebuild.' missing
  • 886386c: 8322890: Directly return in OldPLABSizeConstraintFunc
  • 438ab7c: 8323284: Remove unused FilteringClosure declaration
  • 52c7ff1: 8322330: JavadocHelperTest.java OOMEs with Parallel GC and ZGC
  • ff499ef: 8233443: G1 DetailedUsage class names overly generic for global namespace
  • 37a6172: 8322936: Update blessed-modifier-order.sh for default, sealed, and non-sealed
  • ... and 150 more: https://git.openjdk.org/jdk/compare/1fde8b868a0e40fb79de505106ef07e3dccbd1de...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

@openjdk openjdk bot added ready Pull request is ready to be integrated and removed csr Pull request needs approved CSR before integration labels Jan 9, 2024
@naotoj
Copy link
Member Author

naotoj commented Jan 9, 2024

/integrate

@openjdk
Copy link

openjdk bot commented Jan 9, 2024

Going to push as commit 376051a.
Since your change was applied there have been 163 commits pushed to the master branch:

  • a5071e0: 8322817: RISC-V: Eliminate -Wparentheses warnings in riscv code
  • 28d8149: 8323115: x86-32: Incorrect predicates for cmov instruct transforms with UseSSE
  • e9f7db3: 8322880: Eliminate -Wparentheses warnings in arm32 code
  • aba1933: 8323210: Update the usage of cmsFLAGS_COPY_ALPHA
  • f3be138: 8322809: SystemModulesMap::classNames and moduleNames arrays do not match the order
  • bc05893: 8323318: Remove unused Space::is_free_block
  • dd8ae61: 8322237: Heap dump contains duplicate thread records for mounted virtual threads
  • ee98d26: 8323066: gc/g1/TestSkipRebuildRemsetPhase.java fails with 'Skipping Remembered Set Rebuild.' missing
  • 886386c: 8322890: Directly return in OldPLABSizeConstraintFunc
  • 438ab7c: 8323284: Remove unused FilteringClosure declaration
  • ... and 153 more: https://git.openjdk.org/jdk/compare/1fde8b868a0e40fb79de505106ef07e3dccbd1de...master

Your commit was automatically rebased without conflicts.

@openjdk openjdk bot added the integrated Pull request has been integrated label Jan 9, 2024
@openjdk openjdk bot closed this Jan 9, 2024
@openjdk openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jan 9, 2024
@openjdk
Copy link

openjdk bot commented Jan 9, 2024

@naotoj Pushed as commit 376051a.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
core-libs core-libs-dev@openjdk.org i18n i18n-dev@openjdk.org integrated Pull request has been integrated
6 participants