8343125: Correct the documentation for TreeMap's getFloorEntry and getCeilingEntry

[namannigam]

As the documentation of getCeilingEntry currently reads, the inference is misleading as follows:

if no such entry exists, returns the entry for the least key greater than the specified key;
if no such entry exists (i.e., the greatest key in the Tree is less than the specified key), returns {@code null}
Have modified the first section to ensure that its clear that the value returned is upon existence of the key. Added a similar change for getFloorEntry.

---

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-8343125: Correct the documentation for TreeMap's getFloorEntry and getCeilingEntry (Bug - P5)

Reviewers

• Chen Liang (@liach - Reviewer)
• Archie Cobbs (@archiecobbs - Committer)

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 21729

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

Using diff file

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

Using Webrev

Link to Webrev Comment

[bridgekeeper]

Hi @namannigam, welcome to this OpenJDK project and thanks for contributing!

We do not recognize you as Contributor and need to ensure you have signed the Oracle Contributor Agreement (OCA). If you have not signed the OCA, please follow the instructions. Please fill in your GitHub username in the "Username" field of the application. Once you have signed the OCA, please let us know by writing /signed in a comment in this pull request.

If you already are an OpenJDK Author, Committer or Reviewer, please click here to open a new issue so that we can record that fact. Please use "Add GitHub user namannigam" as summary for the issue.

If you are contributing this work on behalf of your employer and your employer has signed the OCA, please let us know by writing /covered in a comment in this pull request.

[openjdk]

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

8343125: Correct the documentation for TreeMap's getFloorEntry and getCeilingEntry

Reviewed-by: liach, acobbs

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 371 new commits pushed to the master branch:

• c4e7dc7: 8344389: 32-bit builds fail at CDS build time after JDK-8331497
• d76b5b8: 8344253: Test java/util/Spliterator/SpliteratorTraversingAndSplittingTest.java failed
• 3e78ff1: 8320743: AEAD ciphers throw undocumented exceptions on overflow
• 2078329: 8344134: Use static property in SystemLookup
• 162d66a: 8318668: java/lang/management/MemoryMXBean/CollectionUsageThreshold.java fails with Xcomp
• 9b0ab92: 8344034: Remove security manager dependency in Serialization
• d52d136: 8344221: Remove calls to SecurityManager and and doPrivileged in java.net.IDN, java.net.URL, java.net.URLConnection, sun.net.util.URLUtil, and java.net.URLStreamHandlerProvider after JEP 486 integration
• dfddbca: 8341916: Remove ProtectionDomain related hotspot code and tests
• 5eb0733: 8344383: Include ZipArchive and JarArchive directly
• b8b70c8: 8344379: [s390x] build failure due to missing change from JDK-8339466
• ... and 361 more: https://git.openjdk.org/jdk/compare/f1a9a8d25b2e1f9b5dbe8719abb66ec4cd9057dc...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.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@liach, @archiecobbs) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

[openjdk]

⚠️ @namannigam a branch with the same name as the source branch for this pull request (master) is present in the target repository. If you eventually integrate this pull request then the branch master in your personal fork will diverge once you sync your personal fork with the upstream repository.

To avoid this situation, create a new branch for your changes and reset the master branch. You can do this by running the following commands in a local repository for your personal fork. Note: you do not have to name the new branch NEW-BRANCH-NAME.

$ git checkout -b NEW-BRANCH-NAME
$ git branch -f master f1a9a8d25b2e1f9b5dbe8719abb66ec4cd9057dc
$ git push -f origin master

Then proceed to create a new pull request with NEW-BRANCH-NAME as the source branch and close this one.

[openjdk]

@namannigam The following label will be automatically applied to this pull request:

• core-libs

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

[liach]

To get a JBS issue, please open a bug report about this typo in https://bugs.java.com/bugdatabase/. Also follow https://openjdk.org/guide for the rest of the steps for contributions.

[namannigam]

To get a JBS issue, please open a bug report about this typo in https://bugs.java.com/bugdatabase/. Also follow https://openjdk.org/guide for the rest of the steps for contributions.

Thank you for your response @liach, I have

• filed the bug and referenced its ID
• signed the OCA and waiting for its approval

Please help me understand whom to add as a reviewer (and how) for such changes.

[liach]

@namannigam Please take note of #21729 (comment)

Once you have signed the OCA, please let us know by writing /signed in a comment in this pull request.

You have filled in the issue ID correctly; but you need to make sure the PR title has the same text as the issue title. So the correct PR title will be

8343125: Correct the documentation for TreeMap's getFloorEntry and getCeilingEntry

For reviewers, this is the "JDK" project in the OpenJDK census: https://openjdk.org/census#jdk

People don't usually review until a patch (PR) is "rfr" (ready for review), which means that the oca has to be cleared first.

[namannigam]

/signed

[bridgekeeper]

Thank you! Please allow for up to two weeks to process your OCA, although it is usually done within one to two business days. Also, please note that pull requests that are pending an OCA check will not usually be evaluated, so your patience is appreciated!

[mlbridge]

Webrevs

• 02: Full - Incremental (48a0fc1a)
• 01: Full - Incremental (905865a6)
• 00: Full (47b580a8)

[liach]

Looks good.

[archiecobbs]

Looks good to me too.

[stuart-marks]

/csr

[openjdk]

@stuart-marks has indicated that a compatibility and specification (CSR) request is needed for this pull request.

@namannigam please create a CSR request for issue JDK-8343125 with the correct fix version. This pull request cannot be integrated until the CSR request is approved.

[liach]

@stuart-marks Why do we need a CSR for comments on a non-API (package private) method?

[stuart-marks]

/csr unneeded

Sorry, I thought this was changing the specifications. I didn't realize it was an internal method.

The bug report referred to the documentation for the public API ceilingEntry which appears on NavigableMap, but the actual change is to the javadoc comment of an internal method in the TreeMap class.

[openjdk]

@stuart-marks determined that a CSR request is not needed for this pull request.

[liach]

@namannigam FYI you need to issue a /integrate command in a comment if you want to merge this PR.

[namannigam]

/integrate

[openjdk]

@namannigam
Your change (at version 48a0fc1) is now ready to be sponsored by a Committer.

[liach]

Thanks for this comment fix!

/sponsor

[openjdk]

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

• c59adf6: 8344330: Remove AccessController.doPrivileged() from jdk.charsets module
• c4e7dc7: 8344389: 32-bit builds fail at CDS build time after JDK-8331497
• d76b5b8: 8344253: Test java/util/Spliterator/SpliteratorTraversingAndSplittingTest.java failed
• 3e78ff1: 8320743: AEAD ciphers throw undocumented exceptions on overflow
• 2078329: 8344134: Use static property in SystemLookup
• 162d66a: 8318668: java/lang/management/MemoryMXBean/CollectionUsageThreshold.java fails with Xcomp
• 9b0ab92: 8344034: Remove security manager dependency in Serialization
• d52d136: 8344221: Remove calls to SecurityManager and and doPrivileged in java.net.IDN, java.net.URL, java.net.URLConnection, sun.net.util.URLUtil, and java.net.URLStreamHandlerProvider after JEP 486 integration
• dfddbca: 8341916: Remove ProtectionDomain related hotspot code and tests
• 5eb0733: 8344383: Include ZipArchive and JarArchive directly
• ... and 362 more: https://git.openjdk.org/jdk/compare/f1a9a8d25b2e1f9b5dbe8719abb66ec4cd9057dc...master

Your commit was automatically rebased without conflicts.

[openjdk]

@liach @namannigam Pushed as commit e9e4200.

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