8356439: Rename JavaLangAccess::*NoRepl methods

[vy]

NoRepl-suffixed String methods denote methods that do not replace invalid characters, but throw CharacterCodingException on encounter. This behavior cannot easily be derived from the method footprints, has been a source of confusion for maintainers, and is not uniformly adopted, e.g., newStringUTF8NoRepl() and getBytesUTF8NoRepl() does not throw CCE. This PR replaces the NoRepl suffix with NoReplacement in method names and consistently uses throws CCE in method footprints.

---

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

Issue

• JDK-8356439: Rename JavaLangAccess::*NoRepl methods (Enhancement - P4)

Reviewers

• Chen Liang (@liach - Reviewer) Review applies to dae04e9e
• Roger Riggs (@RogerRiggs - Reviewer) Review applies to 584e6e21
• Alan Bateman (@AlanBateman - Reviewer)

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 26413

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

Using diff file

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

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back vyazici! 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]

@vy 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:

8356439: Rename JavaLangAccess::*NoRepl methods

Reviewed-by: alanb, liach, 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 15 new commits pushed to the master branch:

• 3184714: 8325766: Extend CertificateBuilder to create trust and end entity certificates programmatically
• e66ed4d: 8366666: Bump timeout on StressAsyncUL
• ef7872c: 8365163: [ubsan] left-shift issue in globalDefinitions.hpp
• ... and 12 more: https://git.openjdk.org/jdk/compare/7f0cd6488ba969d5cffe8ebe9b95e4ad70982188...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]

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

• core-libs
• nio
• security

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.

[liach]

I strongly suggest against using CCE as the standard exception. The only place that relies on CCE is Files; IAE is more suitable for everywhere else. I recommend adding the special CCE handling in Files alone so we can remove the redundant try-catch everywhere else.

[vy]

@liach, thanks so much for the prompt feedback!

I strongly suggest against using CCE as the standard exception.

Would you mind elaborating on the rationale behind this preference, please?

[liach]

Would you mind elaborating on the rationale behind this preference, please?

If you look at the history of newStringNoRepl, you will find it's originally added for JDK-8201276 in ca48716. Since then, newStringNoRepl has been used by various other sites mostly as a utility. None of those further usages ever used the CharacterCodingException. In fact, in String, the actual implementation throws an IAE that is later wrapped in a CCE. I don't think we should punish all other users of this API just because Files.readString requires this CCE; the CCE wrapping can be moved to Files.readString.

[AlanBateman]

newStringNoRepl has confused several maintainers as it's not immediately obvious that it means "no replace", or more specifically CodingErrorAction.REPORT behavior. So it's good to see this getting attention.

Anyone working on String expects CodingErrorAction.REPLACE behavior so having String methods use methods that don't throw would feel right.

There are "far away" APIs, Files.readXXX was mentioned, that require CodingErrorAction.REPORT behavior methods so having JLA methods throw CharacterCodingException is helpful.

There are other far away APIs such as UUID and ZipCoder that specify a Charset and know that no exception will be throw. They want CodingErrorAction.REPORT behavior except that it's a bug if CharacterCodingException is thrown. These cases catch CCE and throw AssertionError, which is okay, and hopefully we have enough tests in all these area to ensure that it doesn't happen.

Anyway, from a first read of the changes then I think we need to make sure that the method descriptions are accurate. There are several places where "IAE" is mentioned but the methods are changed to throw CCE. IAE is awkward in this area because throwing it, instead of CCE, makes it difficult to know if the handling is correct. There is constant code churn in this area and too easy to introduce a regression and "unexpected exception" if IAE is used to in place of a CharacterCodingException.

Another high level comment from a first read is that it feels like there are two forms needed. One form is REPLACE action and doesn't throw. The other is REPORT action and throws CharacterCodingException. That is what we have already, it's just the naming is awkward. So it may be that it's more about finding good names so that it's clear from all the use sites.

[vy]

There are several places where "IAE" is mentioned but the methods are changed to throw CCE.

@AlanBateman, thanks for the tip. Pushed 10cb72c, which improves Javadoc in such places. While doing so, it also

• Ensures that String Javadoc matches the one shared in JavaLangAccess
• Adds some missing(?) requireNonNull checks, and documents them as well.

[mlbridge]

Webrevs

• 10: Full (a69f9fd3)
• 09: Full - Incremental (dae04e9e)
• 08: Full - Incremental (14c0391a)
• 07: Full - Incremental (fa46a81b)
• 06: Full - Incremental (584e6e21)
• 05: Full - Incremental (a73b446a)
• 04: Full (7af0f351)
• 03: Full - Incremental (c5ddfe62)
• 02: Full - Incremental (f536a341)
• 01: Full - Incremental (1fb8582e)
• 00: Full (5f555a68)

[RogerRiggs]

If CCE should have a constructor with a message, it can be added if you have a clear idea how it would be used.

[vy]

Motivated by @RogerRiggs inquiries, and @AlanBateman's below remark,

Another high level comment from a first read is that it feels like there are two forms needed. One form is REPLACE action and doesn't throw. The other is REPORT action and throws CharacterCodingException.

grouped String methods by doReplace argument in 1fb8582. There are several String methods of the following form:

private static byte[] encode8859_1(..., boolean doReplace) {
    // ...
    if (!doReplace) {
        throwUnmappable(sp);
    }
    // ...
 }

We want to make doReplace = false case visible in the function footprint, and this resulted in:

private static byte[] encode8859_1(..., boolean doReplace) throws CCE { ... }

Though this propagates the checked CCE even for doReplace = true. To avoid this, I've grouped methods by doReplace argument into two:

private static byte[] encode8859_1(...) { ... }
private static byte[] encode8859_1NoReplacement(...) throws CCE { ... }

As a result,

1. doReplace = true call-sites invoke encode8859_1(), replacement will occur, and there is no checked CCE thrown
2. doReplace = false call-sites invoke encode8859_1NoReplacement(), replacement will not occur, and CCE needs to be handled

[liach]

Review still in progress, feel free to ping me more more...

[AlanBateman]

Thanks for the updates, I don't have any more comments.

[liach]

The new OrThrow name is much better!

[vy]

@RogerRiggs, @liach, @AlanBateman, I needed to push a ClassCastException fix in a69f9fd, which further simplified the sneaky-throws logic in String. Would one of you mind, unless you have objections, re-approving the PR, please?

Note that I've attached passing tier1,2 results to the ticket.

[vy]

/integrate

[openjdk]

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

• 3184714: 8325766: Extend CertificateBuilder to create trust and end entity certificates programmatically
• e66ed4d: 8366666: Bump timeout on StressAsyncUL
• ef7872c: 8365163: [ubsan] left-shift issue in globalDefinitions.hpp
• ... and 12 more: https://git.openjdk.org/jdk/compare/7f0cd6488ba969d5cffe8ebe9b95e4ad70982188...master

Your commit was automatically rebased without conflicts.

[openjdk]

@vy Pushed as commit eea50fb.

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